[Doxygen] 독시젠으로 코드 문서 만들기 총정리 (예제 포함)

독시젠(Doxygen)이란?

혹시 특정 회사에서 제공하는 SDK(Software Development Kit)를 사용해 본 경험이 있나요? 있다면, 처음 사용하는 SDK를 이해하기 위해 래퍼런스 매뉴얼을 읽어본 적이 있나요? SDK를 사용하는 사용자를 위한 코드 사용 관련 문서를 래퍼런스 매뉴얼(Reference Manual)이라고 합니다. 이러한 문서에는 API 설명뿐만 아니라 SDK 개요, 특징, 환경 설정, 사용 방법, 주의 사항 등의 많은 정보가 담겨있습니다. 즉, 특정 SDK를 처음 사용한다면 반드시 읽어야 하는 문서입니다.

예시로 Omron Sentech에서 제공하는 래퍼런스 매뉴얼을 보겠습니다.

Reference Manual 예시

위 예시 이미지를 보면, 처음 사용하는 개발자를 위한 Programmer's Guide, 제품 사용을 위한 기초 셋업 방법 그리고 우리가 흔히 보던 API 설명 페이지를 볼 수 있습니다. 사실 이 외에도 다양한 정보를 제공하고 있습니다.

참고로, 위에서 보여준 예시 이미지는 chm(Microsoft Compiled HTML Help) 포맷입니다. chm 외에도 HTML 형태로도 문서를 만들 수 있습니다.

독시젠은 이러한 문서를 작성하기 위한 문서 생성 도구이며, 쉽게 사용하기 위한 GUI 형태의 Doxywizard(Doxygen GUI) 프로그램을 제공하고 있습니다.

Doxywizard(Doxygen GUI) 프로그램

독시젠 문서화 구조 설계하기

앞서 설명했듯이, 독시젠으로 API 설명뿐만 아니라 SDK 소개, 사용 방법 등과 같은 페이지(Page)를 추가할 수 있습니다. 다시 Sentech SDK의 문서를 보겠습니다. 목차를 보면 In the beginning이나 Programmer's Guide는 페이지입니다. SFNC, Camera Interfaces 등도 마찬가지입니다. 참고로, Modules, Clases, Files는 자동 생성된 목차입니다.

하나의 페이지 안에는 섹션(Section)이 다수 존재합니다. 다수의 섹션을 묶어 페이지 상단에 보여주는 것을 TOC(Table of Contents)라고 합니다. TOC에서 섹션 문구를 클릭하면 해당 위치로 이동하게 됩니다. 물론, 페이지에서 다른 페이지로 이동하는 것도 가능합니다.

CHM 문서 구조

즉, 단순히 코드에 주석만 달아서 문서를 만드는 것이 아니라 어떤 내용의 페이지를 넣을 것이고, 각 페이지에는 어떤 섹션을 추가할 것인지도 고려해야 합니다. 문서 작업을 많이 하신 분이라면 아시겠지만, 사용자가 이해하기 쉽게 문서를 잘 만들어야 나중에 유지보수나 A/S에 손이 덜 가게 됩니다.

독시젠 문서화 관련 프로그램 준비하기

독시젠으로 문서를 만들기 위해 Doxywizard는 필수이고, 나머지 두 개는 선택 옵션입니다.

1. Doxywizard(Doxygen GUI)

독시젠을 쉽게 사용하기 위한 GUI를 제공하고 있습니다. 아래 링크를 참고하여 GUI를 준비합니다.

[Doxygen] 윈도우10에서 독시젠(Doxygen) 다운로드 및 설치하는 방법

[Doxygen] 윈도우10에서 독시젠(Doxygen) 다운로드 및 설치하는 방법

2. Graphviz

Graphviz는 그래프를 시각화하는 도구로, 문서화 내에서 클래스 간에 상속 구조를 표현하는 데 사용됩니다. 사실 기본 그래프를 사용해도 되지만, 아주 조금 더 꾸미고 싶다면 해당 도구도 준비합니다.

[Doxygen] Graphviz 적용하여 클래스 다이어그램 표시하기

[Doxygen] Graphviz 적용하여 클래스 다이어그램 표시하기

3. HTML Help Workshop

독시젠은 기본적으로 HTML 문서를 생성합니다. 하지만 문서화 출력 폴더에 너무 많은 HTML 페이지와 리소스가 존재하는데요. chm 파일로 문서를 생성하면 다른 사람에게 chm 파일 하나만 보내도 쉽게 열 수 있습니다. chm 문서를 작성하고 싶다면 아래 링크를 참고하여 준비합니다.

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

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

 

 

독시젠 문서화 옵션 설정하기

Doxygen GUI로 문서를 생성하기 위해 기본적으로 설정해야 하는 옵션들이 있습니다. 아래 링크를 참고하여 기본 옵션을 설정합니다. 만약, GraphViz와 CHM을 사용한다면 앞에서 언급한 링크를 참고하여 추가 설정을 합니다.

[Doxygen] Doxywizard(Doxygen GUI) 프로젝트 기본 설정 방법

[Doxygen] Doxywizard(Doxygen GUI) 프로젝트 기본 설정 방법

독시젠 문법 익히기

소스 코드만 있다고 해서 문서화가 뚝딱하고 만들어지는 것은 아닙니다. 헤더 파일에 독시젠 문법에 맞춰 주석을 남겨야 하고, 필요에 따라 페이지도 생성해야 합니다. 다음은 자주 사용하는 독시젠 문법을 정리한 링크입니다. 해당 문법만 익히면 웬만한 기능은 모두 구현할 수 있습니다.

[Doxygen] 자주 사용하는 소스 코드 주석 및 페이지 문법 사용 방법(예제 포함)

[Doxygen] 자주 사용하는 소스 코드 주석 및 페이지 문법 사용 방법(예제 포함)

 

 

독시젠 예제 코드 및 파일

이전에, MFC 시리즈에서 그림판 만들기 프로젝트를 진행한 적이 있습니다. 해당 프로젝트 코드를 기준으로 독시젠 주석을 생성해 보았습니다.

[MFC] 그림판(mspaint) 만들기 프로젝트 #4 (예제 포함)

[MFC] 그림판(mspaint) 만들기 프로젝트 #4 (예제 포함)

그림판 프로젝트 파일 중 IFigure.h와 Line.h 그리고 Rectangle.h에만 주석을 작성했고, 페이지는 doxygen > pages 경로에 포함되어 있습니다. 자세한 내용은 아래 첨부 파일을 다운로드하세요.

ExamDoxygen.zip

0.44MB

또한 첨부 파일에는 Doxyfile이라는 이름의 Doxygen GUI 설정 파일이 있습니다. 해당 파일로 만든 매뉴얼의 완성본은 아래 첨부 파일을 다운로드하세요.

ExamDocumentation.zip

0.60MB

위 파일에서 html 폴더의 index.html을 실행하면, 매뉴얼의 메인 화면이 표시됩니다. 자, 이제 Doxygen으로 매뉴얼을 만들어 보세요!