최근 업무로 인해 소스코드를 문서화해야 할 일이 생겼다. 소스코드라는 것이 설명하기 참 어렵다. 특히 신호처리나 하드웨어 특성이 반영된 소스코드는 더욱더 설명이 어려운 것 같다. 이전에는 Excel도 활용해 보고 PPT도 활용해 보고 다양한 도구를 활용해 봤지만 Doxygen 만 한 tool이 없다.
Doxygen은 소스코드에 주석을 달아 놓으면 그 주석이 바로 문서화가 되기 때문에 별도로 작업을 해줄 필요도 없고, 문서화에 대해 고민하지 않아도 된다.
그럼 이제 Doxygen의 기본적인 사용법을 알아보자. 이전 포스팅에는 설치방법이 있으니 참고바람
2023.07.20 - [Software/Doxygen 활용한 소스코드 문서화] - Doxygen 설치하기, 소스코드 문서화, source code 문서화
Doxygen 설치하기, 소스코드 문서화, source code 문서화
구글에 doxygen을 검색하면 가장 먼저 나오는 페이지 클릭! https://www.doxygen.nl/ Doxygen: Doxygen Generate documentation from source code Doxygen is the de facto standard tool for generating documentation from annotated C++ sources, but
vuzwa.tistory.com
Doxygen이란?
Doxygen은 소스코드의 주석을 읽어 들여 자동으로 문서화된 문서를 생성해 주는 Tool이다. 개발자는 별도의 문서작업을 하지 않고 소스코드에 주석을 작성하는 것 만으로 문서화를 할 수 있다. 문서화 결과물은 HTML, PDF, LaTex, RTF 등 다양한 형태로 저장할 수 있고 UML 다이어그램과 같은 그래픽요소를 생성해 코드 구조, 구조체, 클래스 등을 시각적으로 표현하는 것도 가능하다. 또한 소스코드에 알고리즘을 수학적으로 표한하는 수학서식도 제공하고 이미지도 추가할 수 있기 때문에 소스코드 문서화에 필요한 거의 모든 기능을 제공한다고 볼 수 있다.
Doxygen 기본설정 및 사용법
Doxygen을 처음 실행하면 아래와 같은 화면이 나온다.
File -> Save 또는 Save as... 을 눌러서. doxygen 파일을 저장한다. Doxygen으로 문서화 생성을 위한 일종의 프로젝트 파일이다. 본 포스팅에서는 C 드라이브에 Doxygen_test 폴더를 만들어서 진행하도록 하겠다.
저장을 마치고 나면 오른쪽 그림과 같이 "Specify the workin directory from which doxygen will run"에 .doxygen 파일을 저장한 경로가 표시 시 된다.
다음으로 문서화시킬 소스코드 경로를 지정해줘야 한다.
Source code directory 가 소스코드가 모여있는 경로인데 이곳에 . 을 입력하면 .doxygen 파일이 있는 경로가 문서화 경로가 된다. 프로젝트 규모가 커서 소스코드가 방대한 경우는 나눠서 작업을 진행하는 게 문서화 측면에서는 더 효율적일 것이라고 생각한다.(개인적인 의견) 그래서 나는 .doxygen 파일이 있는 경로에 문서화시킬 소스코드를 모아서 문서화를 진행한다. 경로지정을 마치고 "Scan recursively " 선택해 줘야 폴더의 하위경로에 포함된 모든 내용 문서화시킨다.
여기까지 지정한 다음 문서화된 결과물을 저장할 경로를 지정해줘야 한다. 이것 또한 소스코드 경로 지정과 마찬가지로 별도의 경로 지정이 가능하고 .doxygen 파일이 있는 폴더로 경로 지정이 가능하다. document 폴더를 만들어서 경로로 지정
Project name과 Project synopsis 그리고 Project version or id를 입력해 주자. 여기까지 완료하고 Mode로 넘어가면 문서화 범위와 최적화시킬 프로그래밍 언어를 선택할 수 있다.
여기서 초기값인 Documented entitirs only를 선택하면 코드에서 주석과 Doxygen 명령어만이 문서화 대상이 된다. 오른쪽 그림과 같이 All Entities를 선택해 소스코드의 모든 내용이 문서화되게 하고, Include cross-referenced source code in the output 옵션을 선택해 링크랑 참조를 포함하도록 설정해 함수, 클래스, 구조체등이 다른 요소와 관련된 소스코드로 쉽게 이동할 수 있게 한다.
보라색 박스는 최적화할 소스코드의 언어를 선택해 준 다음 output으로 이동해 문서화 결과물을 만들어낼 옵션을 선택한다.
위 그림과 같이 선택한다. 윈도우에서 어떤 프로그램에서 F1키를 누르면 도움말 창이 나오는걸 확인 할 수 있는데 이 파일의 확장자가 .chm이다. 문서화된 결과물을 .chm 파일로 만들기 위해 선택하고 다른 옵션도 위 그림과 동일하게 선택한다.
Diagrams 에서 아래 내용과 같이 옵션선택한다. GraphViz라는 Package를 이용해서 함수, 클래스, 구조체의 참조관계등을 UML 다이어그램이로 표현해주기위한 옵션이다.
여기까지 설정하고 Run 탭으로 이동해서 Run doxygen을 눌러보자. 이전에 반드시 소스코드가 준비되어 있어야 한다. 소스코드 용량에 따라 시간이 다소 소요되기도 한다.
완료!! document 폴더로 이동하면 HTML과 LaTex 폴더 두개가 보인다. HTML 폴더로 이동해 Index.html을 검색하면 결과물을 확인 할 수 있다. .chm 파일 옵션을 선택했는데 .chm 파일을 만들기 위해서는 별도의 작업이 필요하다. 우선은 index 파일로 확인해보자.
index 파일을 실행하면 아래와 같이 나온다. 본 포스팅에서는 STM32 기반의 소스코드를 활용했기 때문에 HAL 드라이버에 달려있는 주석의 내용이 문서화됐다.
Project name과 Project synopsis 그리고 Project version or id에 입력한 내용이 문서 상단에 표시된걸 확인 할 수 있다. 여기까지 완료했다면 기본적인 설정은 끝.
다음 포스팅에서는 GraphViz 설치 및 적용과 .chm 파일로 만드는 옵션 설정에 대해 다뤄보도록 하겠다.
- 끝 -
'개발 관련 지식 및 Tool 사용방법 > Doxygen 활용한 소스코드 문서화' 카테고리의 다른 글
| Doxygen 설치하기, 소스코드 문서화, source code 문서화 (0) | 2023.07.20 |
|---|