Doxygen

1. 개요

Doxygen은 소스 코드 주석에서 문서를 추출하여 HTML, CHM, RTF, PDF, LaTeX, PostScript, man 페이지 등 다양한 형식으로 출력하는 문서화 도구이다. C, C++, C#, D, Fortran, IDL, Java, Objective-C, Perl, PHP, Python, VHDL 등 여러 프로그래밍 언어를 지원하며, Qt 툴킷에서 사용되는 문서화 태그를 지원한다. Doxygen은 C++ 클래스 상속 다이어그램을 생성하고 Graphviz의 "dot" 도구를 활용하여 더 발전된 다이어그램과 그래프를 생성할 수 있다. Doxygen은 깃허브에서 소스 코드를 호스팅하며, C++로 작성되었고, 대부분의 유닉스 계열 운영체제, macOS, 윈도우에서 실행된다.

2. 디자인

Doxygen은 자바독과 같이 소스 파일 주석에서 문서를 추출한다. Qt 툴킷에서 사용되는 문서화 태그도 지원한다.

2.1. 지원 언어

Doxygen은 C, C++, C#, D, 포트란, IDL, 자바, Objective-C, 펄, PHP, 파이썬, 및 VHDL을 지원한다. 다른 프로그래밍 언어는 추가 코드를 통해 지원할 수 있다.

2.2. 출력 형식

Doxygen은 HTML, Microsoft Compiled HTML Help(CHM), 서식 있는 텍스트 형식(RTF), PDF, LaTeX, PostScript, man 페이지 형식으로 출력을 생성할 수 있다. 자바독과 마찬가지로, Doxygen은 소스 파일 주석에서 문서를 추출한다.

2.3. 개발 환경

Doxygen은 대부분의 유닉스 계열 운영체제, macOS, 윈도우에서 실행된다.

일부 통합 개발 환경(IDE)은 Doxygen 주석을 바탕으로 툴팁 정보를 표시하거나, 코드 자동 완성 시 함수나 메서드의 매개변수 설명을 제공하기도 한다.

3. 예시 코드

Doxygen은 특수 주석 구문을 사용하여 소스 코드 내에 문서화를 할 수 있다. 일반적인 주석 구문은 `/*` 뒤에 별표(`*`) 또는 느낌표(`!`)를 추가하는 방식이다. 문서의 모든 명령어는 백슬래시(`\`) 또는 앳사인(`@`)으로 시작한다. C++ 스타일의 한 줄 주석(`//`)도 지원하며, 추가 슬래시(`/`) 또는 느낌표(`!`)를 사용하여 Doxygen 주석으로 처리할 수 있다.

```cpp
/**
<간단한 한 줄 설명>

<더 긴 설명>
<필요에 따라 여러 줄 또는 단락으로 구성될 수 있음>

@param someParameter 메서드 또는 함수의 입력 또는 출력 매개변수에 대한 설명
@param ...
@return 반환 값에 대한 설명
*/
```

많은 프로그래머는 각 줄의 시작을 공백-별표-공백으로 표시하는 것을 선호하지만, 필수는 아니다.

```cpp
/// <간단한 한 줄 설명>
///
/// <더 긴 설명>
/// <필요에 따라 여러 줄 또는 단락으로 구성될 수 있음>
///
/// @param someParameter 메서드 또는 함수의 입력 또는 출력 매개변수에 대한 설명
/// @param ...
/// @return 반환 값에 대한 설명
```

LaTeX 명령을 사용하여 수식을 추가하는 등 더 풍부한 마크업도 가능하다.

3.1. C++ 코드 예시

다음은 C++ 소스 파일에서 Doxygen을 사용하는 예시이다.

```cpp
/
* @file
* @brief Time 클래스의 헤더 파일.
* @author John Doe
* @version 1.0
* @copyright CC BY-SA 또는 GFDL.
* @sa Wikipedia:Copyrights - Wikipedia
*/

/
* Time 클래스는 시간의 순간을 나타냅니다.
*
* @author John Doe
*/
class Time {
public:

/
* 시간을 주어진 값으로 설정하는 생성자.
*
* @param timeMillis 1970년 1월 1일 이후 경과한 밀리초 수.
*/
explicit Time(long long timeMillis) {
// the code
}

/
* 현재 시간을 가져옵니다.
*
* @return 현재 시간으로 설정된 Time 객체.
*/
static Time now() {
// the code
}

private:
long long m_timeMillis; ///< 1970년 1월 1일 이후 경과한 밀리초 수.
};
```

`@file`, `@author`, `@version` 등의 다양한 태그를 사용하여 파일, 작성자, 버전 등의 정보를 문서화할 수 있다. `@param`, `@return` 태그를 사용하여 함수의 매개변수와 반환 값에 대한 설명을 추가할 수 있다. 멤버 뒤에 주석을 추가하려면 주석 블록에 추가적인 `<` 마커가 필요하다.

다음은 매개변수를 문서화하는 다른 방법이다.

```cpp
/
* 시간을 주어진 값으로 설정하는 생성자.
*/
explicit Time(long long timeMillis /< 1970년 1월 1일 이후 경과한 밀리초 수. */
)
{
// the code
}
```

LaTeX 명령을 사용하여 방정식을 추가하는 것도 가능하다.

```cpp
/**
*
* 인라인 방정식 @f$ e^{\pi i}+1 = 0 @f$
*
* 표시된 방정식: @f[ e^{\pi i}+1 = 0 @f]
*
*/

4. Doxygen 소스와 개발

Doxygen 소스는 현재 깃허브에서 호스팅되고 있으며, 주 개발자인 디미트리 반 헤스(Dimitri van Heesch)는 "doxygen"이라는 사용자 이름으로 기여하고 있다. Doxygen은 C++로 작성되었으며, 300,000개 이상의 소스 라인으로 구성되어 있다. 어휘 분석을 위해 표준 도구인 Lex (또는 대체 도구인 Flex)가 약 35,000 라인의 렉스 스크립트를 통해 실행된다. 파싱 도구인 Yacc (또는 대체 도구인 Bison)도 사용되지만, 사소한 작업에만 사용되며, 언어 파싱의 대부분은 네이티브 C++ 코드로 수행된다. 소프트웨어 빌드 프로세스는 CMake를 기반으로 하며 일부 파이썬 스크립트도 포함한다.

5. 고급 기능

Doxygen은 소스 코드 주석에서 문서를 생성하는 강력한 도구이지만, 기본적인 기능 외에도 고급 기능을 활용하면 더욱 유용하고 가독성 높은 문서를 만들 수 있다.