Doxygen

목차

1. Doxygen이란

2. Doxygen 사용방법

   - Doxygen 다운로드
   - 프로젝트 폴더 생성

   1) HTML 파일 만들기
   2) CHM 파일 만들기

 

1. Doxygen이란

 

Doxygen은 소프트웨어 레퍼런스 문서 생성기 입니다. 즉, 프로젝트 문서화를 쉽게 할 수 있도록 도와주는 도구입니다.

프로그램을 작성할 때 Doxygen 주석 문법을 사용하여 주석을 달아주면, 그 주석과 프로그램 구조를 토대로 전체 프로그램의 문서를 만들어줍니다. C, C++, C#, Java, PHP 등의 소스코드들로부터 HTML, CHM, PDF, XML 형식의 문서를 생성할 수 있습니다.

 

<참고자료: Doxygen 문법>

/** *기본 주석 형태 */

기본적인 Doxygen 주석 형태

 

/** @file AppMain.c @date 2022/03 @author powerdeng2@naver.com  @version 1.0 @brief 메인 소스 파일 */

Doxygen 파일 주석 예시

 

/** @fn                              unsigned char ParaSave(stPD* pstPD, signed short wData, unsigned char Ch, unsigned char IsComReq) @brief                          파라미터 저장 및 체크 함수 @param pstPD           stPD 타입 구조체 포인터 @param wData          저장 요청 데이터 @param Ch                 드라이버 인덱스 @param IsComReq     통신 드라이버에서의 호출 여부 @return                          ok(0), false(other) */

Doxygen 함수 주석 예시

 

2. Doxygen 사용방법

 

- Doxygen 다운로드

[그림1] Doxygen 다운로드 링크 화면

 

https://www.doxygen.nl/download.html

Doxygen: Downloads

위의 링크를 따라가면 [그림1]과 같은 화면이 나오는데 OS에 따라 Doxygen을 다운로드 할 수 있다. 여기서는 Window 64bit를 예로 들어 표시해놓았다.

다운로드 후 파일을 설치하면 Doxywizard라는 프로그램이 생성된다.

 

 

- 프로젝트 폴더 생성

① Doxygen으로 문서화하고 싶은 프로젝트의 소스파일을 복사한다.

 

② 새롭게 만들 프로젝트 폴더를 생성한다.

[그림2] ② 예시

 [그림2]를 보면 새롭게 만들 프로젝트의 폴더를 Nuc029sge_flow2로 만들고 그 안에 또 폴더를 생성하여 분류하였다.

 

③ ①에서 복사한 소스코드를 분류된 폴더에 맞게 붙여 넣는다.

[그림3] ③ 예시

 

<주의사항>

- #if, #endif와 같은 전처리기는 소스코드에서 제거해야 한다.

- 소스코드에 Static 함수가 있다면 일반 함수로 변경해야 한다.

- 소스파일의 인코딩 방식을 UTF-8로 변경한다.

 

 

1) HTML 파일 만들기

 

<참고자료: HTML 파일>

HTML은 Hyper Text Markup Language 약어로 HyperText(웹 페이지에서 다른 페이지로 이동할 수 있도록 하는 것)기능을 가진 문서를 만드는 언어이다.

HTML파일은 HTML 언어로 이루어진 파일이다.

 

① 다운로드 받은 Doxywizard라는 프로그램 실행한다.

[그림4] Doxywizard 프로그램 실행 화면

 

② 생성될 프로젝트 루트 폴더를 지정한다.

[그림5] 생성될 프로젝트 루트 폴더를 바탕화면으로 지정한 화면

 

③ 앞에서 만든 소스 파일이 있는 프로젝트 폴더를 지정하고 모든 하위 폴더를 재귀적으로 스캔 하겠다는 Scan recursively에 체크한다.

[그림6] 1)-③ 예시

 

④ 프로젝트 이름과 버전을 지정하고 Next를 누른다.

[그림7] 1)-④ 예시

 

⑤ Mode에서 각 함수마다 사용한 함수로의 링크를 생성하겠다는 All Entities, Include cross-referenced source code in the output에 체크하고 소스코드 언어를 선택한 뒤 next를 누른다(여기서는 소스코드가 c언어로 작성되어서 c 선택).

[그림8] 1)-⑤ 예시

 

⑥ Output에서 문서 왼쪽에 탐색 트리를 보여준다는 with navigation panel에 체크하고 next를 누른다.

[그림9] 1)-⑥ 예시

 

⑦ Diagrams에서 소스 간의 관계를 GraphViz로 표현해준다는 Use dot tool from the GraphViz package에 체크하고 아래 모든 항목 체크 한다.

[그림10] 1)-⑦ 예시

 

⑧ Expert의 Project에서 출력 결과에 쓰여질 언어를 한국어로 선택하고 항상 상세 정보를 보여준다는 ALWAYS_DETAILED_SEC에 체크한다.

[그림11] 1)-⑧ 예시

 

⑨ Expert의 Source Browser에서 함수 설명 시 함수 코드를 보여준다는 INLINE_SOURCES에 체크한다.

[그림12] 1)-⑨ 예시

 

⑩ 아래 링크에서 GraphViz를 설치합니다.

https://www.graphviz.org/download/

Download

[그림13] 링크 화면

 

⑪ Expert의 dot에서 다이어그램을 UML 형식으로 그린다는 UML_LOOK에 체크한 뒤 DOT_PATH를 지정합니다(DOT 프로그램은 GraphViz를 의미하며 1)-⑩에서 다운로드 했다면 경로는 C:\Program Files\Graphviz\bin 입니다.)

[그림14] 1)-⑪ 예시

 

⑫ Run에서 Run doxygen을 클릭하여 문서를 생성한다.

[그림15] 1)-⑫ 예시

 

⑬ html 폴더에서 index를 열면 My Project 1.0.0으로 HTML 파일이 생성된 것을 확인할 수 있다.

[그림16] 생성된 HTML 파일

 

<참고자료>

https://www.slideshare.net/arload/doxygen-33932243

Doxygen 사용법

 

2) CHM 파일 만들기

 

<참고자료: CHM 파일>

Microsoft Compiled HTML Help의 약자로, 마이크로소프트에서 개발한 도움말 포맷입니다. 이 CHM은 HTML 페이지 모음과 목차, 색인, 검색 등의 기능을 제공하며 주로 제작사 측에서 SDK 전반적인 내용과 Library Reference 자료를 포함하여 배포합니다.

 

① CHM 파일을 생성하기 위해서는 HTML Help Workshop의 hhc.exe 파일이 필요합니다. 컴퓨터에 아래의 파일이 있는지 확인합니다.

C:\Program Files (x86)\HTML Help Workshop\hhc.exe

 

없다면 아래 첨부된 파일(htmlhelp)을 설치합니다.

htmlhelp.zip

3.30MB

 

② HTML 파일을 만들 때와 같이 1)-①부터 1)-⑤까지 동일하게 진행한다.

 

③ Output에서 CHM 파일을 만들겠다는 prepare for compressed HTML(.chm)에 체크하고 next를 누른다.

[그림17] 2)-③ 예시

 

④ HTML 파일을 만들 때와 같이 1)-⑦부터 1)-⑨까지 동일하게 진행한다.

 

⑤ 한글 깨짐 현상을 해결하기 위해 아래 첨부된 파일(iconv-1.9.2.win32)에서 bin폴더 안에 iconv라는 프로그램을 설치하고 그 위치를 기억한다.

iconv-1.9.2.win32.zip

1.25MB

 

<참고자료: 한글 깨짐 현상>

CHM 파일의 목차를 생성하기 위해서는 index.hhc 파일을 사용하게 되는데 이 파일이 UTF-8 형식으로 작성되어 있다 보니 한글이 깨지게 됩니다. 그래서 index.hhc 파일을 CP949 형식으로 변환만 해주면 해결이 되는데 이를 위해 iconv라는 프로그램을 사용하는 것입니다.

 

⑥ 아래 첨부된 배치 파일(hhc converter)을 설치한다.

hhc converter.zip

0.00MB

 

⑦ 배치 파일(hhc converter)을 오른쪽 클릭 후 편집을 누른다.

 

⑧ 아래 [그림18]에서 밑줄 친 부분을 2)-⑤에서 설치한 iconv.exe의 경로로 수정한다.

[그림18] 배치 파일(hhc converter)

 

<참고자료: 배치 파일[그림18] 추가 설명>

 

● C:\Users\rnd5800\Downloads\iconv-1.9.2.win32\bin\iconv.exe

→ Iconv.exe의 경로를 의미한다.

 

● -f UTF-8 -t CP949 index.hhc

→ index.hhc 파일을 UTF-8 포맷에서 CP949 포맷으로 변환하겠다는 것을 의미한다.

 

● > temp.hhc

→ 결과물로 temp.hhc 파일을 생성하겠다는 것을 의미한다.

 

● del index.hhc

→ 변환 전의 index.hhc 파일을 삭제하겠다는 것을 의미한다.

 

● move temp.hhc index.hhc

→ temp.hhc 파일 이름을 index.hhc 파일 이름으로 변경하겠다는 것을 의미한다.

 

● "C:\Program Files (x86)\HTML Help Workshop\hhc.exe" "%1"

→ hhc.exe를 실행한다는 것을 의미한다.

 

⑨ Expert의 HTML에서 생성한 CHM 파일의 이름을 작성하고 2)-⑧에서 수정한 배치 파일(hhc converter)의 경로를 지정한다.

[그림19] 2)-⑨ 예시

 

⑩ HTML 파일을 만들 때와 같이 1)-⑩부터 1)-⑫까지 동일하게 진행한다.

 

⑪ html 폴더에 2)-⑨에서 작성한 이름의 CHM 파일이 생성된 것을 확인한다.

[그림20] 2-⑪ 예시

<참고자료>

https://luckygg.tistory.com/343

[Doxygen] HTMLHelp로 chm파일 만들기(+ 목차 한글 깨짐 해결 방법)