Doxygen 사용법 (자세한 가이드)

출처 : http://neotrinity.egloos.com/943385

Doxygen Guide !!!

*Doxygen 기본 스타일

  /** */

*주석안에 아이템들

@breif ==> 설명을 쓴다. 여러줄을 쓸때에는 @breif를 쓰고 한줄 띄운다움 계속해서 
              쓰면된다.
@file ==> 파일 이름을 구별할때.
@return ==> 함수의 리턴값 나타낼때.
@author ==> 작성자 이름을 나타낼때
@date ==> 작성날짜를 나타낼때.
@param ==> 함수 파라메터를 나타낼때
@see ==> 참고할 함수나 페이지를 지정한다.
@todo
@bug
@code ==>중요 코드를 설명할때 시작 지점 가리킨다.
@endcode ==> 중요코드 설명할때 종료 지점 가리킨다.
@exeception
@mainpage
@section

====클래스 처리===
@class ==> 클래스명 나타낼때.
*클래스 멤버에대한 처리
/// 이렇게 표시한다.(단 멤버 상단에 표시할것!!)
/**< 내용 */ 이렇게도 표시한다. (멤버 옆에)
///< 이렇게도 표시한다.(멤버옆에)
  
====enum 타입처리====
*상단에 @brief로 무엇을 하는것인지 나타내고
각각의 멤버에 대해서는.
/*!< 내용 */  이렇게 표시한다. (멤버 옆에)
/**< 내용 */ 이렇게도 표시한다. (멤버 옆에)
///< 이렇게도 표시한다.(멤버옆에)

===중요 코드도 주석을 단다.===
@code 로 시작해서
@endcode 로 끝낸다.

예제)
    /**
     * @brief 예제코드
     *
     *  추가설명
     * @code
       *........
       * @endcode
     */

 

1          기본 원칙

1.1    주석작성의 목적은 자기 자신뿐만이 아니라 다른 사람들을 위한 작업이다. 
(따라서 자기만 알아볼 수 잇는 약어를 사용하거나 농담으로 주석을 작성하면 안된다.)

1.2          주석은 모국어로 기입한다. 
(아무리 타국어를 잘하는 사람이라도 모국어보다 타국어를 잘할 수 없다. 또한 다른 사람들을 위한 배려이다.)

1.3          주석은 항상 최신으로 유지가 되어야한다. 
(코드를 변경한 이후에는 반드시 관련 주석을 함께 변경해야한다. 최신이 아닌 주석은 오히려 코드 분석에 큰 방해가 된다.)

1.4          헤더파일의 손상을 최소화한다. 
(헤더파일은 개발자가 가장 자주 접근하는 파일이다. 무분별한 여러라인의 주석추가로 인하여 헤더파일 자체의 분석능력을 떨어뜨리다면 개발자는 결국 열기 불편한 문서파일만 접근하게 될것이다.)

1.5          중복된 주석 입력 작업은 최소화 한다. 
(함수의 인자를 설명하기 위해서 그 인자를 중복해서 입력할 필요는 없다. 동일한 클레스 멤버 함수의 설명주석을 헤더와 구현 파일에중복하여 기입 할 필요가 없다. 불필요한 중복된 주석입력 작업은 주석입력을 꺼리게 만드는 계기가 된다. 단 클래스와 같이중요도가 매우 높은 항목은 예외로 한다.)

1.6          Doxygen은 파일, 클래스, 구조체, 멤버변수, 멤버함수, 일반함수등에만 사용한다. 
(Doxygen의 모든 문법과 방법을 사용하여 너무 많은 활용을 하는 것은 오히려 코드가 보기 좋지 않고 가독성이 떨어지게 된다.)

1.7          함수의 주석은 동사로 끝을 맺고 변수나 인자, 객체의 주석은 명사로 끝을 맺는다. 
(함수는 행위를 나타내고 변수는 객체를 나타내기 때문이다.)

1.8          무분별한 주석추가는 자제한다. 
(아주 어려운 알고리즘이 아니라면 라인단위로 주석을 다는 것은 코드의 가독성을 해치게 된다.)

1.9          주석 입력작업의 목적은 코드를 알아보기 좋게 하는 작업이므로 모든 사항을 지나치게 철저하게

         지킬 필요는 없다.

2 Doxygen 형식

2.1          소스 파일의 최상단에 파일명, 날짜, 제작자, 설명등을 명기한다. 
(주석의 방식이/**, */인것에 주의한다. h, inl, cpp등 모든 소스파일에 표기한다.)
예)
/**     
        @file      RHttp.h
         @date    2004/11/2
         @author개똥이

                    RapidEngine™
      @brief    hello world  소스파일.

      파일여러줄 설명입니다.\n
      진짜 여러줄 입니다.\n
      음.. 하나. 둘. 셋
      넷다섯.
*/

메인페이지(MainPage)를 두어 프로그램의 전체 개요 등을 적어줄 수 있다.
/**
  @mainpage   Hello World 메인페이지
  @section intro 소개
  - 소개      :   프로그램의 기본을 배울수있는 프로그램.
  @section developer 개발자

        - 이상호 
  @section   Program 프로그램명
  - 프로그램명  :   Hello World 프로그램.
  - 프로그램내용    :   화면에 Hello World!을 출력한다.
  @section info 개발목적

         - Doygen 문서 테스트용 소스

         @section advenced 추가정보

         - 글머리는 '-' 태그를 사용하면 되며

         - 탭으로 들여쓸경우 하위 항목이 된다.

         -# 번호매기기는 '-#' 방식으로 할수 있다.

         -# 위와 같이 탭으로 들여쓸경우 하위 항목이 된다.

         -# 두번째 하위 항목

         -이런식으로 그림을 넣을수도 있다.

           \image html gom.jpg

  @section  INOUTPUT    입출력자료
  - INPUT           :   없음.
  - OUTPUT      :   Hello World 화면출력.
  @section  CREATEINFO      작성정보
  - 작성자      :   infiniterun
  - 작성일      :   2005/04/18
  @section  MODIFYINFO      수정정보
  - 수정자/수정일   : 수정내역
  - infiniterun/2005.0418    :   "Helo World"에 "!"추가
  */

2.2          클래스 및 구조체 인터페이스 윗부분에 클래스명, 날짜, 제작자, 설명등을 첨부한다. 
(주석의 방식이/**, */인것에 주의한다.)
예)
/**
         @class  CRHttp
         @date    2004/11/2
         @author 개똥이

                   @brief    Http 클라이언트 
         @warning 몇몇 서버상의 오류로 가능한 업로드는 소문자로 한다. (특히 하나포스 마이홈)
*/
class CRHttp
{
                     …
};

2.3          클래스 / 구조체 멤버 변수 주석은 공백 1칸을 띄우고 “///<” 를 사용한다. 
예) 
long m_lFrameTic; ///< 1000/fps로 이시간후 (ms) 프레임을 이동한다. 
long m_lNewTime; ///< 최종 프레임 진행 시간 

2.4          클레스 멤버 함수는 헤더에 “///<”을 사용하고 추가 설명, 리턴값 및 인자에 대한 필요하다면 구현부분에 추가 설명을 입력한다. 
선언부 예)
DWORD* Decode( DWORD* pBuffer, DWORD* pSize ); ///< 암호화 버퍼와 변경된 size리턴 (4바이트 증가)

구현부 예)
/**
        @return찾은 그룹  (없으면 NULL)
        @warning 외부에서 관련된 동기화 객체를 Lock을 걸어 사용한다. 
*/
CRGroup* CRServer::FindGroup( RGID gid ///< 그룹 아이디 
                                               )
{
}

2.5          일반 함수는 헤더에 “///”을 사용하고 추가 설명, 리턴값 및 인자에 대한 필요하다면 구현부분에 추가 설명을 입력한다. 
선언부 예)
/// 하위폴더 포함하여 디렉토리를 생성한다. 
extern BOOL CreateXDirectory( LPCTSTR szPath );

구현부 예)
/**
        @return디렉토리 생성 성공유무 
         @warning King\kong\file.dat와 같은 파일명은 포함 안된다.
*/
BOOL CreateXDirectory( LPCTSTR szPath ///< 생성할 디렉토리명 (예:C:\\King\\kong, King\\kong\\)
                                  )
{
}

3  일반 형식

3.1          주석은 설명하는 구문의 앞 라인에 작성한다.
올바른 예)
// 파일의 크기가 설정되지 않았다면…
if( nSize == 0 )
{
        return  FALSE;
}

잘못된 예)
if( nSize == 0 ) // 파일의 크기가 설정되지 않았다면…
{
        return  FALSE;
}

if( nSize == 0 ) 
{        // 파일의 크기가 설정되지 않았다면…
         return  FALSE;
}

      3.2     define, 전역변수 사용법
                #define MAX_READ_BUF   1024    /**< 최대 read buffer size      */
                short  port;                   /**< Telnet port number */


예제소스>>
**
  @file     hello.c
  @brief    hello world  소스파일.

  파일여러줄 설명입니다.\n
  진짜 여러줄 입니다.\n
  음.. 하나. 둘. 셋
  넷다섯.
  */

/**
@mainpage Hello World 메인페이지
  @section intro 소개
  - 소개      :   프로그램의 기본을 배울수있는 프로그램.
  @section   Program 프로그램명
  - 프로그램명  :   Hello World 프로그램.
  - 프로그램내용    :   화면에 Hello World!을 출력한다.
  @section  INOUTPUT    입출력자료
  - INPUT           :   없음.
  - OUTPUT      :   Hello World 화면출력.
  @section  CREATEINFO      작성정보
  - 작성자      :   infiniterun
  - 작성일      :   2005/04/18
  @section  MODIFYINFO      수정정보
  - 수정자/수정일   : 수정내역
  - infiniterun/2005.0418    :   "Helo World"에 "!"추가
  */

#include <stdio.h>


#define MAX_READ_BUF   1024    /**< 최대 read buffer size      */

short  port;                 /**< Telnet port number */

/**
  @brief buffer structor

  Telnet에서 정송되는 데이터에 대해 프로토콜을 처리해야 하기 위하여,
  효율적으로 데이터를 전송해야 할 입출력 버퍼 structor
  */
struct  buffer
{
  char       *buf;  /**< 데이터를 저장할 주소공간   */
  int        size;   /**< buf에 할당된 메모리 크기   */
  int        head;   /**< buf에 저장된 데이터의 처음 Index   */
  int        tail;   /**< buf에 저장된 데이터의 마지막 index */
  int        count; /**< buf에 저장된 데이터의 byte 수      */
};

/** @brief TRUE FALSE정의. */
enum BOOLEAN
{
  FALSE=0,        /**< FALSE */
  TRUE           /**< TRUE */
};

/**
  @brief     hello Main 함수.

  긴 설명은 한줄을 넘긴다음 넣어준다. \n
  하나둘. 셋.. 넷.. 
  다섯.. 여섯.. \n

  @return    성공여부.
  */
int main(
       int    argc,       /**< 인자개수 */
       char * argv[]     /**< 인자 */
       )
{
  printf("Hello World!\n");
  return 0;
}


주석을 달때 다음과 같은 형식으로 달라구 나오죠.. 

/** 
*/ 

/*! 
*/ 

//! 
//! 
//! 

/// 
/// 
/// 

맘에드는거 알아서 사용하십쇼! 



  
대충 나름대로 주석의 성격대로 스패샬 커맨드를 함께 사용해 정리를 해봤는데요 
  
(1) 파일 디스크립션(용어가 참 부적절하네 -_-  .. 브리핑이라고 해야하나) 
  
           /** \file <파일이름> 
               \brief <브리핑> 
               \author <제작자> 
               \warning <경고성 멘트> 
               \version <버전> 
               \date <날짜>   
           */ 
  
(2) 함수 디스크립션 
           /** \fn <함수 이름> 
               \brief <브리핑> 
               \param <파라메터 설명> 
               \return <리턴값 설명> 
               \sa <See also 함수 링크> 
               \warning <경고성 멘트> 
               \date <날짜> 
           */