:: 전산쟁이의 카피질

출처 : http://alones.byus.net/tt/722

Doxygen 설치와 작성, 문서 생성 (1.5.2 버전 기준) 에 대해서 정리해보았다.

매일 회사에서 설치/설정된 대로 또 회사의 규칙대로 쓰다 보니 막상 집에서 사용하려고 하니 귀찮은 일이 한 두개가 아니어서 이 번에 최신 버전을 받아서 설치하면서 정리했다.

-_-;; 1.5.2의 한글 문제는 어서 해결이 되었으면 좋겠다. (혹시 주석내 한글 처리 1.5.2에서 되게 할 수 있는 분은 가르켜 주시면 감사하겠습니다.

최신 내용은 아래 wiki에서 볼 수 있다.

in my wiki: http://alones.byus.net/moniwiki/wiki.php/tools_doxygen?action=show

initial version: 2007.07.17

이 글을 쓰고 있는 시점의 버전이 1.5.2를 기준으로 설명한다. 예전에 사용하고 있던 것 보다 HTML도 이쁘고 wizard도 편리해진 것 같다. 예전엔 주로 Visual Studio 6.0의 플러그인 버전을 사용했었지만 IDE에 종속되는 느낌이 있어서 독립적인 Doxygen 프로그램을 사용하기로 했다.

Doxygen으로 코드를 문서화 하는 것에 대해서 간단히 설명하고 설치와 Doxygen 문서 생성, tip 등에 대해서 다루겠다.

※ Doxygen comment에 사용되는 special comment (e.g. @brief)에 대한 것은 References의 링크를 참고

2 Doxygen으로 코드를 문서화 하기 #

Doxygen으로 코드를 문서화 할 때 쓰는 방식은 JavaDoc, Qt, 두개의 c++ 주석 (i.e. ////) 등 여러 가지가 있고 또 이 것을 혼용해서 쓸 수도 있다.
Doxygen 사이트의 Documenting the Code 페이지를 보면 알 수 있다. 나 자신이 써온 것을 위에 것에서 찾으면 JavaDoc에 가까운 것 같다. (정확히 일치한지는 모르겠다)

※ 아래 Tips & Warning에서도 이야기 하고 있지만 1.5.2에서는 주석의 한글이 제대로 처리되고 있지 않다. 하위 버전에서는 잘 사용하고 있었는데 ㅜ.ㅜ

2.1 File #

헤더나 소스 파일에는 파일명과 간략한 설명, 저자, history 정도를 기술 해주면 될 것이다. 이 것의 예는 다음과 같다. (제 스타일 대로)


/**
 * @file        AloExcelAuto.h
 * @brief       CAloExcelAuto class 
 * @author      alones
 * @date        initial version: 2007.07.18
 * @date        second revision: 2007.07.18
 */
...
//

2.2 Class #

class에는 class 명과 간략한 설명 정도를 기술하면 될 것이다.


/**
 * @class CAloExcelAuto
 * @brief excel automation class
 */
class CAloExcelAuto
//

2.3 Class 멤버 변수 #

다음과 같이 각 멤버 변수에 대해서 작성할 수 있을 것이다.

private:
        long    m_nFd;  /**< fd for checking invalid*///

2.4 Class 멤버 함수 또는 일반 함수 #

함수에 대한 설명이나 in/out 파라미터, 리턴 값 정도와 참고할 함수 예제 코드 정도를 기술하면 될 것이다. 이에 대한 것들을 예제로 작성해보면 다음과 같을 것이다.

@see의 경우는 함수만 있으면 함수 명을 쓰면 자동 링크 된다.
@code ~ @endcoe 에 코드를 넣으면 된다.
@addtogroup는 각 함수 등을 moudle로 묶어 주는 역할을 해준다. 실제 doxygen을 생성하면 tree에 Modules라는 부분이 추가되어있고 @addtogroup이 같은 항목들끼리 묶여져 있다.


/**
 * @brief               open excel file
 * @param[in]   strpath (std::string) excel path
 * @param[out]  nError (int&) error code
 * @code
 *              int nError;
 *              bool Open("test.xls", nError);
 * @endcode
 * @return              if sucess ture, otherwise false
 * @see                 Close();                
 * @addtogroup  Util
 */
bool Open(std::string strPath, int& nError);
//

1.1 define이나 변수 선언 #

#define 정의나 변수에 대한 것은 다음과 같이 작성할 수 있을 것이다.


/**
 * temp file for parsing
 */
#define TEMP_FILE       "TEMP_FILE" 

/** 
 * file fd for temp file 
 */
int gnFd;
//

1.2 struct나 enum #

struct나 enum은 다음과 같이 작성할 수 있을 것이다.

/**
 * test enum
 */
enum TestEnum
{
        ONE = 1, /**< one */
        TWO,     /**< two */
};

/**
 * test struct
 */
struct TestStruct
{
        int nA;         /**< int value */
        bool bB;        /**< bool value */
};
//

2 Doxygen 설치 #

Doxygen 사이트에 접속해서 binary를 다운 받는다.
- Doxygen download page에서 중간 정도에 있는 Doxygen source and binary releases에서 최신 버전의 binary를 다운 받는다 (※ 이 글을 쓸 때는 1.5.2였다).

3 DoxyWizard로 간단하게 Doxygen 만들어 보기 #

DoxyWizard로 간단하게 Doxygen 문서 (html, LaTex, xml, chm, etc)를 만들 수 있다. Doxygen은 "Config"를 가지고 작업을 수행한다. 말 그대로 설정 파일이며 이 것은 DoxyWizard의 UI에서 수정할 수도 있고 직접 파일을 수정할 수도 있다. 아무튼 Doxygen 문서를 만들 때 Doxygen 프로그램은 "Config" 파일을 필요로 하고 아래 설명은 Config 파일을 DoxyWizrd를 이용해서 생성/설정하고 Config 파일을 이용해서 Doxygen 문서를 만드는 것에 대해서 간단히 설명한다.

DoxyWizard를 수행시키면 아래와 그림과 같은 다이얼로그가 보이고, Doxygen을 만드는 4단계 별로 구성되어 있다.

3.1 Step1. Configuration Doxygen #

Doxygen을 만들 때 wizard로 쉽게 만들 것인지 expert로 좀 더 다양한 설정을 할 것인지 아니면 기존에 만들어 둔 설정을 로딩할 것인지를 결정한다.

3.1.1 Wizard #

Wizard:처음 만들 때 간단하게 Project 명과 버전, 소스 위치와 출력물이 나올 경로만 선택해주면 된다.
물론 Output이나 Diagrams에서 기타 설정을 할 수 있다.
Wizard를 클릭하면 아래와 같은 다이얼로그가 나오고 위에서 거론된 정보들을 입력하고 "OK" 버튼을 클릭하면 된다.

3.1.2 Expert #

Expert는 Wizard에서 가능한 설정을 포함해서 좀 더 다양한 설정을 할 수 있다. 아래에 소개되는 chm 파일도 Expert에서 설정할 수 있다.

3.1.3 Load... #

기존에 만들어 둔 Config를 로딩하는 기능이다.

3.2 Step2. Save the configuration file #

위에서 설정한 configuration 파일을 저장한다. Step 1의 "Load..."에서 나중에 읽어 드릴 수 있고 또한 이 파일을 이용해서 Doxygen 문서를 만들어 낸다.

3.3 Step3. Specify the directory from which to run doxygen #

Working directory를 설정한다. working directory는 doxygen이 실행될 위치로 소스 패스를 설정하면 될 것이다.

3.4 Step4. Run doxygen #

모든 설정이 완료 되었으면 "Start" 버튼이 활성화 될 것이고 버튼을 클릭하면 로그 창에서 분주하게 doxygen 문서를 생성하는 것이 보일 것이고 완료가 되면 지정한 출력 폴더에 doxygen 문서들이 보일 것이다.

4 chm (도움말) 파일 만들기 #

Doxygen을 html로 만드는 것도 유용하지만 아래 그림과 같이 chm 파일로 Doxygen을 만드는 것도 배포하기도 편해서 필요할 것이다.

Doxygen에서 chm 파일을 만드는 것에 대해서 간단히 설명하면 아래와 같다.

4.1 MS HTML Help 설치 확인 #

먼저 Microsoft HTML Help가 있는지 확인하고 없다면 설치한다.
먼저 Microsoft HTML Help를 다운로드 받는다.
- 아래 링크 (msdn)에서 받을 수 있고 링크가 접속이 안될 때는 chml이나 MS HTML Help Compiler로 검색하면 쉽게 찾을 수 있다
  - Microsoft HTML Help Downloads의 HTML Help Workshop
설치하고 경로를 기억해둔다. (hhc.exe 위치가 필요하기 때문이다)
※ e.g. C:\Program Files\HTML Help Workshop\hhc.exe

4.2 DoxyWizard 설정 #

DoxyWizard 실행
기존 설정한 config 파일이 있으면 "Load"를 클릭해서 로딩한다.
"Expert..." 버튼을 클릭한다.
"HTML" 탭에서 중간 정도의 "GENERATE_HTMLHELP"를 선택한다.
바로 아래의 CHM_FIL에 chm 파일 이름을 기재한다.
※ 별도 경로를 기재하지 않으면 html이 생성되는 위치에 생성된다.
"HHC_LOCATION"에 위에서 설치 확인한 MS HTML Help의 hhc.exe의 위치를 설정하낟.
확인을 누르고 doxygen을 생성하면 html 경로에 chm 파일이 생성될 것이다.

5 Tips & Cautions #

5.1 Config 파일 수정 #

DoxyWiard에서 할 수 있는 설정들은 config 파일을 열어서 직접 각 option들을 수정함으로써 가능하다.

5.2 Tree 보여주기 #

HTML에서 프레임이 나누어져서 왼쪽에 탐색을 할 수 있는 트리를 보여주기 위해서는 다음과 같이 설정해주면 된다.

DoxyWizard의 "HTML" 탭에서 하단의 "GENERATE_TREEVIEW"를 체크해주면 된다.

5.3 class의 protected나 private 보여주기 #

아무런 설정 없이 doxygen 문서를 만들면 private이나 protected 함수는 doxygen에 나타나지 않는다. 이러한 것들을 모두 doxygen 문서에 나타내고 싶은 경우
DoxyWizard의 "Expert"의 "Build" 탭에서 EXTRACT_로 시작하는 부분을 체크해주면 된다. "EXTRACT_PRIVATE"을 클릭하면 private 함수들이 보여지는 식이다.

5.4 한글 보여주기 문제 #

일단 1.5.2 하위 버전에서는 한글을 큰 무리 없이 잘 사용했었는데 1.5.2에서는 encoding 방식을 아무리 바꾸어 보아도 한글이 제대로 보여지지 않는다. References의 Doxygen 1.5.2 한글 문제에서도 지적하고 있다.
일단 그래도 시도하고 싶은 분을 위해서 한글 설정은 DoxyWizard 의 "Expert"에서 "Project"의 "DOXYFILE_ENCODING"에서 인코딩 방식을 변경해서 시도해 볼 수 있다. 기본이 UTF-8이고 한글을 위해서는 아래와 같은 것들이 제공된다고 하지만 다 시도해봤지만 헛 수고 였다.

Korean 
EUC-KR, CP949, ISO-2022-KR, JOHAB

인코딩 관련 설명은 아래 사이트에서 볼 수 있다.
doxygen은 libiconv라는 라이브러리를 이용해서 언어처리를 하고 있고 libiconv의 인코딩 방식은 아래 사이트에 열거되어 있다.
Introduction to libiconv

6 References #

Doxygen 사이트
Doxygen 사이트의 메뉴얼 페이지
Documenting the Code
Doxygen 1.5.2 한글 문제
Doxygen Configuration에 옵션 등의 문서
DoxyWizrd 사용 가이드
- doxygen 문서화에 대한 지침
Doxygen special comments
- "@brief" 등에 대해 설명