Doxygen with PHP

From 흡혈양파의 인터넷工房
Jump to navigation Jump to search
gentoo의 php에서 Doxygen을 사용하는방법


관련자료


Doxygen준비하기

Doxygen의 설치

  1. 아래의 명령을 사용해서 설치하면 된다.
    emerge doxygen
  2. doxygen 이라는 명령어를 쳐서 실행이 된다면 정상적으로 설치가 된것이라 볼 수 있다


Doxygen의 준비

별도로 설정파일을 마련하는게 아니라면 다음과같은 방법을 사용해서 기본설정파일을 만들어 이후 작업을 준비할 수 있다 

# doxygen -g 만들어질설정파일이름


Doxygen의 사용

php 소스가 있는 디렉토리에서 다음의 명령어를 실행한다 

# doxygen 만들어놓은설정파일이름


php에 Doxygen의 주석을 넣는법

  1. 일단 메인으로 사용할 파일을 하나 지정하고 php파일내에 다음과같은 주석을 넣는다
    <?php
/// @mainpage 프로젝트이름
/// @section intro 소개
/// - 소개      :   프로젝트에 대한 소개
/// @section Project 프로젝트이름
/// - 프로그램명  :   프로젝트이름
/// - 프로그램내용    :  프로젝트에 대한 상세한 내용
/// @section CREATEINFO 작성정보
/// - 작성자      :   작성자
/// - 작성일      :   작성일(임의대로입력)
/// @section MODIFYINFO 수정정보
/// - 수정자/수정일   : 수정내역

?>
  2. 각 파일마다 다음과같은 정보를 제일 위쪽에 넣어준다
    /// @file       현재주석을넣고있는파일명
/// @brief      현재쟈주석을가지고있는파일에대한주석
  3. 파일 내부에서 함수에 대한 주석을 넣고자 할때는 다음과같은 형식으로 주석을 넣어주면 된다
    /// @brief      cut string in utf-8
/// @author gony (http://mygony.com)
/// @param $str     source string
/// @param $len     cut length
/// @param $checkmb if this argument is true, function treat multibyte character as two bytes. default value is false.
/// @param $tail    abbreviation symbol
/// @return string  processed string
/// @author     onion
/// @date       20130417
/// @bug        nothing
/// @todo       nothing
/// @exception  nothing

function strcut_utf8($str, $len, $checkmb=true, $tail='...')
  4. 다른 php파일에 대한 주석 작업을 할때는 @mainpage 등에 대한 주석은 사용할 필요가 없다.
  5. Class 등을 작업하는경우에는 좀 더 다른 규칙을 사용해야할 필요가 있다.
  6. 이렇게 다 작업이 완료되면 doxygen의 대상이 되는 php파일들이 모여있는 디렉토리에서 다음과같은 명령어를 이용해서 document를 생성할 수 있다
    # doxygen 만들어놓은설정파일이름
  7. 기본 설정파일내용대로라면 html 과 latex 으로 된 결과물을 얻을 수 있다. html 의 경우는 web browser 를 이용해 확인하면 된다


php의 Function 대한 Doxygen 주석의 아주 간단한 예제

<?php
       /**
       * @brief        function:: db_open//데이터베이스 open시에 사용하는 함수
       * @param        in_db_name :: 데이터베이스 이름
       * @param        in_db_user :: 데이터베이스 사용자 이름
       * @param        in_db_pass :: 데이터베이스 사용자에 대한 비밀번호
       * @return       connect 를 반환한다. 관련된 정보는 php의 connect 변수 부분을 참조
       * @author       onion
       * @date 20130417
       * @bug  nothing
       * @todo nothing
       * @exception    nothing
       **/
       function db_open($in_db_name='', $in_db_user='', $in_db_pass='')
       {
       global $db; // global database discriptor 변수

       if( empty($in_db_name) )
               $in_db_name = $db["name"];
       if( empty($in_db_user) )
               $in_db_user = $db["user"];
       if( empty($in_db_pass) )
               $in_db_pass = $db["pass"];
       $connect=mysql_connect('localhost' , $db["user"], $db["pass"] );

       if ( $connect  ==false )
       {
           echo("접속에 실패했습니다 뭔가 문제가 있는듯 하군요. 데이터서버의 점검을 바랍니다") ;
           exit ;
       }

       mysql_select_db($db["name"],$connect);

       return $connect ;
       }
?>


php의 Class에 대한 Doxygen 주석의 아주 간단한 예제

<?php

/** 
* @file sample2.php
* 
* @brief Class와 Grapvhviz에 대한 예제파일
* 
**/

/** 
* @class Vegetable
* 
* @brief 야채에 관련된 클래스
* 
* 야채에 관련된 좋은 클래스 예제
*/

class Vegetable {

   var $edible;
   var $color;

   /** 
   * @brief Vegetable 메서드
   * 
   * Vegetable 메서드에 대한 자세한 설명
   */

   function Vegetable($edible, $color="green")
   {
       $this->edible = $edible;
       $this->color = $color;
   }


   /** 
   * @brief is_edible 메서드
   * 
   * is_edible 메서드에 대한 자세한 설명
   */

   function is_edible()
   {
       return $this->edible;
   }


   /** 
   * @brief what_color 메서드
   * 
   * what_color 메서드에 대한 자세한 설명
   */

   function what_color()
   {
       return $this->color;
   }

} // Vegetable 클래스 끝


/** 
* @class Spinach
* 
* @brief Vegetable 을 확장한 클래스
* 
* Vegetable 을 확장한 클래스에 대한 좋은 예제
*/

class Spinach extends Vegetable {

   var $cooked = false;

   /** 
   * @brief Spinach 메서드
   * 
   * Spinach 메서드에 대한 자세한 설명
   */

   function Spinach()
   {
       $this->Vegetable(true, "green");
   }


   /** 
   * @brief cook_it 메서드
   * 
   * cook_it 메서드에 대한 자세한 설명
   */

   function cook_it()
   {
       $this->cooked = true;
   }


   /** 
   * @brief is_cooked 메서드
   * 
   * is_cooked 메서드에 대한 자세한 설명
   */

   function is_cooked()
   {
       return $tiis->cooked;
   }

} // Spinach 클래스 끝

?>

위의 경우처럼 주석을 넣고 Doxygen 의 설정파일에서 graphviz에 대한 option을 켜주면 class에 대한 hiarachy의 그래프를 볼 수 있다


주의사항

  • class의 선언시 Class 가 대문자면 안된다. 무조건 소문자여야함. (아마도 C++ 이나 java 등의 영향이 있는게 아닐까.. 생각됨)


참고자료







Retrieved from "https://workspace.onionmixer.net/mediawiki/index.php?title=Doxygen_with_PHP&oldid=395"