Alones world

1 Doxygen 소개

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

2.1 File

2.2 Class

2.3 Class 멤버 변수

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

1.1 define이나 변수 선언

1.2 struct나 enum

2 그룹핑 (Grouping)

3 그래프와 다이어그램 그리기

3.1 Graphviz 설치

3.2 설정

4 Doxygen 설치

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

5.1 Step1. Configuration
Doxygen

5.1.1 Wizard

5.1.2 Expert

5.1.3 Load…

5.2 Step2. Save the
configuration file

5.3 Step3. Specify the
directory from which to run doxygen

5.4 Step4. Run doxygen

6 chm (도움말) 파일 만들기

6.1 MS HTML Help 설치 확인

6.2 DoxyWizard 설정

7 Tips & Cautions

7.1 Config 파일 수정

7.2 Tree 보여주기

7.3 class의 protected나
private 보여주기

7.4 한글 보여주기 문제

8 References

• @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();                
 */
bool Open(std::string strPath, int& nError);

• 그룹의 선언: defgroup
  • 그룹명과 그룹에 대한 설명을 선언할 수 있다.
  • 여러 파일일 경우 한 파일에만 선언해주면 된다.
• 그룹에 포함: ingroup
  • 클래스나 함수를 그룹에 포함 시킬 수 있다.
  • 클래스를 그룹에 포함시켰으면 클래스 멤버 함수는 그룹에 대해서는 ingroup을 사용할 필요는 없다.

예제는 다음과 같다.

/** @defgroup group1 The First Group
 *  group1이라는 그룹을 선언했다.
 */

/** 
 * @brief class C1 은 group1에 속하게 된다.
 * @ingroup group1
 */
class C1 {};

/**
 * @brief fucn1은 group1에 속하게 된다.
 * @ingroup group1
 */
void func1();

//

• “Expert” , “Dot” 탭에서 그리고자 하는 그래프와 다이어그램을 설정한다.
• “DOT_PATH”에 설치한 Graphviz의 bin 폴더를 지정해준다.

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

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

• 먼저 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

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

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

==== 파일명 축약해서
보여주기 ====

• 생성된 Doxygen 문서의 파일 트리에서 파일 명이 전체 경로로 나와있으면 보기 불편하기 아래 설정을 통해서 파일명만 보여줄 수 있다.
  • “Expert”, “Project” 탭, “FULL_PATH_NAMES” 체크 해제

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

• 1.5.2에서는 한글이 조금 문제였지만 (물론 INPUT_ENCODING을 CP949로 하면 된다) 1.5.4에서는 EUC-KR 등으로 변경해도 한글이 잘
  나온다.
• 입력되는 소스 코드의 한글 주석을 위한 인코딩 방식은 “DoxyWizard”, “Expert”,”INPUT”의
  “INPUT_ENCODING”에 아래 방식들을 선택하면 된다.

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

• 생성된 페이지에 대한 한글 처리는 “DoxyWizard”, “Expert”, “Project”의
  “DOXYFILE_ENCODING”에서 인코딩 방식을 변경한다.
• 인코딩 관련 설명은 아래 사이트에서 볼 수 있다.
• doxygen은 libiconv라는 라이브러리를 이용해서 언어처리를 하고 있고 libiconv의 인코딩 방식은 아래 사이트에 열거되어
  있다.
• Introduction to
  libiconv

• 
  Doxygen 사이트

• [Doxygen 사이트의
  Doxygen 사이트의 메뉴얼 페이지

• 
  Documenting the Code

• Doxygen 1.5.2 한글
  문제

• 
  Doxygen Configuration에 옵션 등의 문서

• DoxyWizrd 사용
  가이드
  • doxygen 문서화에 대한 지침

• 
  Doxygen special comments
  • “@brief” 등에 대해 설명

• 
  Doxygen Grouping에 대한 설명