Doxygen 주석으로 생성하는 코드 문서

개발자는 다른 사람이 만든 코드를 사용할 때 보는 매뉴얼이 있습니다.

OpenAI API Document

TensorRT API Document

위 그림과 같이 무엇을 하려면 어떤 URL에 어떤 내용을 요청해야 하는지, 함수가 하는 일과 인자는 무엇을 전달해야 하는지 상세히 다룬 내용입니다.

이런 문서를 소스 코드와 별개로 관리한다면 소스 코드의 수정이 있을 때마다 각각 수정 해야하는 번거로움과 수정 내용이 반영이 되지 않는다면 문서 내용에 결점이 생길 수도 있습니다.

이런 문제를 해결하기 위해 구글링 중 Doxygen을 찾았고, 실무에 사용하기 위해 공부하고 포스팅 했습니다.

Doxygen ❓

💡 Doxygen(/ˈdɒksidʒən/ DOK-see-jən) 은 도큐멘테이션 생성기이자 소프트웨어 참조 설명문을 작성하기 위한 도구이다. 여기서 설명문은 코드 내에 작성되므로 상대적으로 최신화 상태를 유지하기가 용이한 편이다. Doxygen은 설명문과 코드를 상호 참조할 수 있으며 문서의 독자는 쉽게 실제 코드를 참조할 수 있다. wikipedia

처음에 들었을 때 한번에 와닿지 않았지만 다른 라이브러리를 사용하면서 한번쯤 보셨을 내용이라고 생각됩니다.

Example code

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
/**
 * \brief Multiplies two numbers.
 *
 * This function multiplies a number times another number and returns the
 * result of those two numbers multiplied together. The result is the product
 * of the two numbers, and that is the value that is returned by this function.
 *
 * \param x The first operand.
 * \param y The second operand.
 *
 * \return The product of `x` and `y`.
 */
int multiply(int x, int y);

위 소스에서 주석으로 된 부분, \brief, \param, \return 등 특정 키워드를 읽어 HTML Document로 만듭니다.

💡 Tips
Doxygen은 C++을 위한 문서 생성기이지만 C, Objective-C, C#, PHP, Java, Python, IDL(Corba, Microsoft 및 UNO/OpenOffice 버전)과 같은 널리 사용되는 다른 프로그래밍 언어도 지원합니다.

Install

Mac OS, Windows, Linux 등 다양한 플랫폼에 설치 가능하며, 이 곳에서 바이너리를 받아 설치하거나 각 리눅스 배포판의 패키지 관리자를 이용해서 설치하셔도 무방합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
❯ dnf install doxygen-doxywizard
마지막 메타자료 만료확인 1:27:23 이전인: 2023년 05월 15일 (월) 오후 07시 54분 12초.
종속성이 해결되었습니다.
==================================================================================================================================
 꾸러미                                      구조                   버전                             레포지터리              크기
==================================================================================================================================
설치 중:
 doxygen-doxywizard                          x86_64                 2:1.9.6-7.fc38                   fedora                 307 k
종속 꾸러미 설치 중:
 clang15-libs                                x86_64                 15.0.7-4.fc38                    fedora                  21 M
 clang15-resource-filesystem                 x86_64                 15.0.7-4.fc38                    fedora                  12 k
 doxygen                                     x86_64                 2:1.9.6-7.fc38                   fedora                 4.8 M
 llvm15-libs                                 x86_64                 15.0.7-4.fc38                    fedora                  25 M
 xapian-core-libs                            x86_64                 1.4.20-2.fc38                    fedora                 757 k

연결 요약
==================================================================================================================================
설치  6 꾸러미

총계 내려받기 크기: 52 M
설치된 크기 : 236 M
진행할까요? [y/N]: y

💡 Tips
doxygen-doxywizard는 GUI입니다. Windows는 Installer를 다운받아 설치하시면 설치됩니다.

Usage 🛠️

주석의 시작은 /** 또는 /*!로 시작하고 */로 끝나며 주석 내용에 들어갈 커맨드는 backslash \를 사용하거나 at-sign @을 사용합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
/**
 * @file main.cpp
 * @author JongBin Park (jongbin@devbin.kr)
 * @brief doxygen 샘플 코드
 * @version 0.1
 * @date 2023-05-16
 * 
 * @copyright Copyright (c) 2023
 * 
 */

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
/*!
 * \file main.cpp
 * \author JongBin Park (jongbin@devbin.kr)
 * \brief doxygen 샘플 코드
 * \version 0.1
 * \date 2023-05-16
 * 
 * \copyright Copyright (c) 2023
 * 
 */

자주 쓰는 커맨드는 아래 표와 같이 정리했으며 더 자세한 내용은 이 곳을 참고하시면 됩니다.

💡 Tips
VS Code를 사용하신다면 Doxygen Documentation Generator 확장 플러그인을 설치해서 사용해보세요!

Useful commands ❤️

Command	Explanation
@brief	간략한 설명
@details	상세한 설명
@param [Parameter name]	인자에 대한 설명
@return	반환형에 대한 설명
@see	참고 내용
@note	주의할 내용
@warning	경고 내용
@pre	사전에 준비해야 할 내용
@todo	해야할 일
@bug	버그 내용

Sample code

💡 Tips
Doxygen 주석 안 파일, 함수, 클래스의 이름이 오면 자동으로 하이퍼 텍스트 링크를 생성합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
/**
 * @mainpage Sample
 * 
 * 
 * @file main.cpp
 * @author JongBin Park (jongbin@devbin.kr)
 * @brief doxygen 샘플 코드
 * @version 0.1
 * @date 2023-05-16
 * 
 * @copyright Copyright (c) 2023
 * 
 */
#include <iostream>

/**
 * @brief 시험 관련 클래스
 * 
 */
class Test
{
protected:
    int score;

    Test() {}
    virtual ~Test() {}

    /**
     * @brief 시험을 시작합니다.
     * @todo
     * 구현을 해야합니다!
     * 
     */
    void start() {}
    /**
     * @brief 시험을 종료합니다.
     * @bug
     * 종료가 되지 않습니다.
     * 
     */
    void end() {}
    
    virtual void mark() = 0;
};

/**
 * @brief 수학 시험 관련 클래스
 * 
 */
class Math : public Test
{
public:
    /**
     * @brief 채점 로직
     * 
     * @details
     * 채점하여 Test 클래스의 score 변수에 점수를 저장합니다.
     * 
     */
    void mark() {}
};

/**
 * @brief 메인 함수
 * 
 * @details
 * *Doxygen* 은 *Markdown* 을 지원합니다!
 * 
 * 또한 *HTML Tag* 를 <b>사용</b>할 수 있습니다.
 * 
 * @param argc 인자 수
 * @param argv 인자로 들어온 내용
 * @return 정상이면 0을 반환 
 * 
 * @see
 * 해당 코드는 깃에 게재되어 있으며 [이 곳](https://github.com/JongBin-Park/doxygen-sample-cpp)을 눌러 이동합니다.
 * 
 * @todo
 * 해당 코드는 샘플 코드이므로 다른 로직이 구현되어야 합니다.
 * 
 * @note
 * 코드가 구현되지 않았습니다.
 * 
 * @warning
 * 프로그램 시작 함수입니다. 없애면 안됩니다.
 * 
 * @pre
 * 해당 함수를 실행하기 전 반드시 인자를 넣어주세요.
 * 
 * @bug
 * 다음 패치에서 수정될 예정입니다
 */
int main(int argc, char **argv)
{
    int testData;

    return 0;
}

doxygen 주석을 모두 추가했다면 관련 설정 파일을 만든 후 문서를 생성하면 됩니다.

Generate template

아래 명령어로 설정 파일 템플릿을 생성한 후 기호에 맞게 파일을 수정합니다!

1
2
3
4
5
6
7
8
❯ doxygen -g doxyfile
Configuration file 'doxyfile' created.

Now edit the configuration file and enter

  doxygen doxyfile

to generate the documentation for your project

수정할 내용은 프로젝트 이름, 버전, 설명, 언어, In/Output 등이 있으며 설정을 다 하셨다면 아래 코드를 이용하여 문서를 생성합니다.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
❯ doxygen doxyfile
warning: The selected output language "korean" has not been updated     
since release 1.8.15.  As a result some sentences may appear in English.

Doxygen version used: 1.9.1
Searching for include files...
Searching for example files...

...

lookup cache used 7/65536 hits=1 misses=8
finished...

⚠️ Warning
Graphviz 관련 오류가 나온다면 관련 패키지를 설치 후 다시 시도해주세요.

Result 🧪

generate document

Doxygen ❓#

Example code#

Install#

Usage 🛠️#

Useful commands ❤️#

Sample code#

Generate template#

Result 🧪#