Doxygen with PHP

From 흡혈양파의 인터넷工房
Jump to: navigation, 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 등의 영향이 있는게 아닐까.. 생각됨)


참고자료