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

Doxygen 사용을 위한 본문은 아래 링크를 참고하세요.

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

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

Doxygen 문법

독시젠은 마크다운(Markdown)과 HTML, XML 명령어 모두 지원합니다. 그리고 문서를 만들기 위해서는 Doxygen 문법대로 작성해야 합니다. Doxygen은 많은 기능을 제공하지만, 본문에서는 그중에서도 가장 많이 사용되는 문법만 정리해 보았습니다.

Doxygen의 기본 문법은 아래 링크를 먼저 참고하셔도 되겠습니다.

https://www.doxygen.nl/manual/docblocks.html

Doxygen Manual: Documenting the code

앞으로 이어질 설명에는 소스 코드에서 주석을 작성하는 방법과 페이지를 추가하고 페이지에서 본문을 작성하는 방법을 설명하겠습니다.

소스 코드의 주석 작성 방법

Doxygen 주석 형식

독시젠 주석의 시작은 /*!이고, 끝은 */입니다. 이 방법 외에도 ///또는 /**도 있긴 하지만, 개인적인 취향으론 아래 방식을 선호합니다.

/*!
* 메시지 
*/

그리고 메시지를 남길 때 맨 앞에 *표시는 없어도 되지만, 이것도 취향 차이입니다.

독시젠 명령어를 사용할 때 \또는 @를 사용합니다. 예시는 아래와 같습니다.

/*!
@section
*/

/*!
\section
*/

namespace, class 주석 달기

namespace와 class형식은 간단합니다.

/**
* @namespace Figure
* @brief [목록에 보여지는 짧은 설명]
*/
namespace Figure
{
	/**
	* @class Line
	* @brief [목록에 보여지는 짧은 설명]
	*/
	class Line : public IFigure
	{
    	//...
    }
}

위 주석은 아래와 같이 표시됩니다. 사실 @namespace [이름]또는 @class [이름]을 굳이 적지 않고, namespace나 class바로 위에 @brief [설명]만 적어도 됩니다.

namespace와 class의 설명

함수 주석 달기

함수의 주석은 기본적으로 아래와 같이 작성합니다.

/**
* @details 두 정수를 더하는 동작을 수행합니다.
* @param[in] a 숫자1
* @param[in] b 숫자2
* @param[out] c 결과
* @return void
*/
void Sum(int a, int b, int *c);

위 기본 형에 bug나 todo, see also, example 등의 내용도 추가할 수 있습니다. 이에 대한 내용은 계속해서 설명하겠습니다.

할 일(To Do), 주의 사항(Warning) 등 사용자에게 참고 메시지 표시하기

메시지 표시

SDK 래퍼런스 매뉴얼(Reference Maunal)에서 아래에 표시한 참고(see also) 또는 위와 같이 경고(warning)나 전제조건(precondition)을 본 적이 있을 겁니다.

참고(see also) 마크

위와 같은 마킹은 아래의 문법을 사용합니다.

* @note 참고 설명
* @todo 할 일 설명
* @pre 미리 호출해야 할 사항
* @bug 버그 설명
* @warning 참고 링크, 페이지
* @see 참고할 함수 또는 페이지

아래와 같이 작성하고 문서를 생성해 보겠습니다.

/**
* @details 두 정수를 더하는 동작을 수행합니다.
* @param[in] a 숫자1
* @param[in] b 숫자2
* @param[out] c 결과
* @return void
* @warning int 형만 지원합니다.
* @bug 버그 사항
* @todo 해야 할 일
* @see 이곳에 페이지, 함수 이름을 작성하면 자동 링크됩니다. Sub() 참고.
*/
void Sum(int a, int b, int *c);

맨 마지막 참고에 Sub()의 링크가 자동 생성되어 연결됩니다.

함수에 메시지 표시하기

함수에 예제 코드(Example code) 연동하기

함수 설명 아래에 예제 코드를 연결하여 참고하라고 강조할 수 있습니다. 단, Doxywizard에서 EXAMPLE_PATH에 샘플 코드가 추가되어 있어야 합니다.

/**
* @details 그리는 동작을 합니다.
* @param g Graphics Handle
* @return void
* @note 사용자에게 알려주고 싶은 내용 작성
* @pre  해당 함수 호출 전 필수 사항 작성
* @bug  버그가 있다면 작성
* @warning 주의 사항 작성
*/
virtual void Draw(Gdiplus::Graphics* g) override;
/** \example example.cpp
* 이 예제는 Figure::Line Class를 어떻게 사용하는지 예시를 보여줍니다. 더 자세한 내용은 Figure::Line Class를 참고하세요.
*/

Doxygen GUI에서 Exptert > Input > EXAMPLE_PATH 항목에 샘플 코드 경로를 추가하세요.

위 예제 코드의 문서 결과는 다음과 같습니다. API 설명 하단에 예제가 추가되었고, Navigation에도 예제 목록이 추가됐습니다. example.cpp를 클릭하면 예제 코드와 설명이 보입니다.

example code 추가한 결과

페이지 작성 방법

저는 관리의 편의성을 위해 페이지를 위한 별도의 텍스트 파일을 사용하고 있습니다. 소스 코드의 주석은 *.h에서 작성하고, 페이지는 *.txt에서 관리하는 것이죠.

주의

 

 

일반 메모장으로 *.txt파일을 생성하면 UTF-8 포맷으로 한글이 깨지게 됩니다. Notepad++ 또는 Visual Studio에서 일반 텍스트 파일을 생성하여 CP949 또는 EUC-KR 포맷을 사용해야 한글이 정상적으로 표시됩니다.

메인 페이지 추가하기

텍스트 파일을 생성하고 아래와 같이 주석을 작성합니다.

/*! @mainpage 메인 페이지
* 내용
*/

메인 페이지는 매뉴얼 파일 실행 시 최초로 보이는 페이지입니다.

서브 페이지 추가하기

메인 페이지 외에도 일반 페이지를 작성할 수 있습니다. 일반 페이지는 다음과 같이 주석을 작성합니다.

/*! @page subpage_1 서브 페이지
* 내용
*/

참고로 subpage_1은 해당 페이지의 이름입니다. 다른 곳에서 이 이름을 작성하면 자동으로 해당 페이지로 링크되는 것이죠.

메인 페이지에서 서브 페이지 연동하기

메인 페이지에서 서브 페이지를 어떻게 연동하는지 보겠습니다. 메인 페이지는 @mainpage커맨드를 사용합니다.

/*! @mainpage 메인 페이지
* Doxygen 매뉴얼을 실행하면 보여지는 첫 페이지입니다.\n
* Doxygen을 사용하는데 있어 가장 기본적인 사용 방법은 @subpage tips_page 페이지를 참고하세요.\n
*/

결과는 다음과 같습니다. 목차를 보면 '메인 페이지'에 'Doxygen 팁'이라는 페이지가 하위로 존재합니다. 그리고 메인 페이지의 내용에는 'Doxygen 팁'이라는 링크가 걸려있고, 클릭하면 해당 페이지로 이동합니다.

메인 페이지와 서브 페이지 연동 결과

페이지에서 섹션(Section) 추가하기

하나의 페이지에 많은 내용을 서술하다 보면, 섹션을 나누는 것이 가독성에 좋습니다. 이러한 섹션은 @section커맨드를 사용합니다.

/*! @page subpage_1 서브 페이지
*
* @section section_1 섹션 1
* 내용
*/

section_1도 마찬가지로 섹션의 이름입니다. 페이지 내에서 섹션 이름을 작성하면 자동으로 해당 섹션으로 이동합니다.

서브 섹션(Subsection) 추가하기

섹션 내에서도 하위 섹션이 필요할 때 쓰이는 명령어입니다. @subsection커맨드를 사용합니다.

* @section procedure_sec Step by step 절차 예시
* 어떤 절차에 대한 순서를 설명하는 경우가 있습니다.\n
* 아래와 같이 Section 링크를 연결하여 설명을 작성할 수 있습니다.\n
* @ref step1 과 @ref step2 를 주의 깊게 진행하세요.
* 
* @subsection step1 Step 1
* 1단계에 대한 설명.
* @subsection step2 Step 2
* 2단계에 대한 설명.

섹션과 마찬가지로, step1과 step2는 서브 섹션의 이름입니다. 위 예시처럼 @ref step1을 작성하면 step1이 자동 링크됩니다.

서브 섹션 추가된 모습

목차(TOC, Table of Contents) 만들기

하나의 페이지에 많은 섹션을 나누면, 일반 사용자는 무슨 내용이 있는지 알기도 힘들고 일일이 스크롤 내리기도 힘듭니다. 이를 위해 페이지 상단에 목차를 넣어주면 편리하겠죠?

/*! @page subpage_1 서브 페이지
* @tableofcontents
*
* @section section_1 섹션 1
* 내용
*/

@tableofcontents를 추가하면 자동으로 목차를 생성해 줍니다.

페이지에 목차가 생성된 모습

하이퍼링크(Hyperlink) 추가하는 방법

본문에 설명을 작성하다 보면, 외부 사이트 주소를 작성하는 경우가 있습니다. 이는 다음과 같이 사용합니다.

* @section link_sec 링크 삽입 예시
* 다음과 같이 링크를 삽입할 수 있습니다.
* [LuckyGg](https://luckygg.tistory.com/)에 오시면 개발에 관련된 많은 정보를 보실 수 있습니다.\n
* @note 자주 방문해주세요 :)

아래와 같이 LuckyGg 단어에 하이퍼링크가 추가되어, 클릭하면 해당 사이트로 이동하게 됩니다.

하이퍼링크 추가된 모습

소스 코드의 클래스 또는 함수 연동 방법

페이지에서 소스 코드에 존재하는 클래스 또는 함수를 언급할 수도 있는데요. 링크는 자동 생성되기 때문에 아래와 같이 사용하면 됩니다. 단, 네임스페이스가 존재한다면 전체 다 작성해야 합니다.

Figure::IFigure

만약, 네임스페이스는 제외하고 클래스 이름이나 함수 이름만 작성하고 싶다면 아래와 같은 방법도 있습니다.

\ref Figure::IFigure "IFigure"

@ref명령어를 사용하여 Figure::IFigure를 IFigure라는 이름으로 연동하는 것이죠.

클래스 또는 함수 연동 결과

표(Table) 추가하는 방법

클래스를 설명하는 표를 작성해 보겠습니다. 위에서 설명한 클래스 이름도 넣어 봤습니다.

* @section table_sec 표 삽입 예시
* 표는 다음과 같이 삽입합니다.
*	항목								|				설명
*	--------------------------------|---------------------------------
*	\ref Figure::IFigure "IFigure"	|	도형 인터페이스
*	\ref Figure::Line "Line"		|	IFigure를 상속받은 Line Class

아주 간단하죠?

표 삽입 결과

표의 셀 병합 방법은 아래 링크를 참고하세요.

https://www.doxygen.nl/manual/markdown.html#md_tables

Doxygen Manual: Markdown support

이미지 추가하는 방법

먼저, Doxygen GUI에서 Expert > Input > IMAGE_PATH에 이미지 파일이 존재하는 파일 또는 경로를 추가합니다. 그리고 아래의 명령어를 사용합니다.

* @section image_sec 이미지 삽입 예시
* 이미지는 다음과 같이 삽입합니다.
* @image html test_image.png "캡션 삽입"

이미지 삽입 결과

인용 문구 추가하는 방법

인용 문구는 >를 사용합니다. 한 줄 또는 여러 줄도 가능합니다.

* @section quote_sec 인용 문구 삽입 예시
* 인용 문구는 다음과 같이 삽입합니다.
* > LuckyGg의 Doxygen입니다.\n
* > 이렇게 여러 줄 삽입이 가능합니다.

인용 문구 삽입 결과

코드 예시(Code snippet) 추가하는 방법

본문에서 코드 예시를 설명하는 경우도 있겠죠. 코드는 @code{.cpp}로 시작하여 @endcode로 끝납니다.

* @section code_sec 코드 삽입 예시
* 코드는 다음과 같이 삽입합니다. 자동으로 클래스 및 함수가 링크됩니다.
* @code{.cpp}
* #include "Line.h"
* Figure::Line object;
* object.Draw();
* @endcode

코드 예시 삽입 결과

더 자세한 독시젠 커맨드를 확인하려면 아래 링크를 참고하세요.

https://www.doxygen.nl/manual/commands.html

Doxygen Manual: Special Commands