doxygen의 사용

doxygen을 사용하고 있는데 아주 만족한다.

그동안 부족했던 C++ 소스 문서화가 깔끔하게 해결되고 있다.

doxygen을 사용하면서 자주 쓰는 기능들을 모아 두었다.

1. Confige 파일 설정

한국 사람이기 때문에 언어를 한국어로 맞춘다.

이거 안해 주면 한글 주석이 모두 깨지는 경우가 있다. (요새는 괜찮을 지도 모르겠다.)

OUTPUT_LANGUAGE  = Korean-en

개인적으로 주석에서 자동으로 brief가 생기는 것이 편한데 기본 설정이 아니라서 다시 설정해 준다.

JAVADOC_AUTOBRIEF = YES

doxygen에서 바로 소스를 열람하기를 원하기 때문에

SOURCE_BROWSER = YES

가끔 매크로 expand가 되어야 클래스, 함수 등이 doxygen에 보이는 경우가 있다.

매크로로 클래스 정의가 되는 경우가 있기 때문이다.

이럴 경우 아래의 두가지를 정의하여 해결한다.

MACRO_EXPANSION = YES

EXPAND_ONLY_PREDEF = YES

위의 두가지가 정의되면 predefine에 들어있는 매크로 들만 expand하게 된다.

꼭 확장해야 하는 매크로들은 아래 처럼 설정한다.

EXPAND_AS_DEFINED = DEFINE_CLASS

컴파일러 종속적인 코드(예:__declspec(dll)같은 것)때문에 doxygen이 이상해지는 경우가 있다.

이럴 때는 이것을 아래와 같이 정의하면 된다.

PREDEFINED  = __declsepc(x):=

위에서 ':='를 쓴 이유는 공백으로 치환해야 하기 때문이다.

딴 것으로 치환하려면 '='를 쓰고 치환될 것을 적는다.

VC의 경우 하나의 솔루션에 여러 개의 프로젝트가 존재할 경우가 많다.

이럴 때는 대부분의 설정이 들어 있는 Main config 파일과 이것을 include 해서 프로젝트별 종속 자료를 가지고 있는 project config로 분리해서 사용하는 것이 편하다.

솔루션 디렉토리에 Main config 파일을 만들고, 프로젝트 디렉토리에 sub config파일을 만든다.

그리고 sub의 첫줄에서

@include = ../MainConfig

하면 된다.

2. 주석 명령

클래스 주석, 함수 주석, 변수 주석은 javadoc처럼 자동으로 인식된다.

굳이 "/** @class Name */" 을 넣을 필요는 없다. (강제 지정할 필요가 없다는 말이다.)

강제로 설정할 경우는 파일에 대한 주석을 달기 위한 @file 밖에 없을 듯 하다.

예외 문자로 사용되는 것은 !, @, \ 세가지가 있다.

이중에서 개인적으로 가장 선호하는 것은 @이다.

일단 타이핑하기 가장 좋은 위치에 있고, 이쁘다.

2.1. 기본 명령

함수의 설명에는 아래와 같은 두가지 기능을 자주 사용한다.

@param p1 

@return

말 그대로 인자 설명과 리턴값 설명이다.

이때 인자 설명은 모든 인자에 대해서 사용하지 않을 경우 doxygen compile시 에러를 출력하기 때문에 주의해서 사용한다.

@param 의 경우 함수 뿐 아니라 template 등에서 공통적으로 사용된다.

2.2. 그룹 명령

자주 사용하는 특별한 기능은 @name 과 @{, @}를 통한 그룹이다.

보통 함수나 클래스의 경우 몇가지가 비슷한 기능을 하기 때문에 주석을 한꺼번에 다는 것이

편할 때가 있다.

이때 좋은 것이 그룹이다.

/**

@name brief description

description

@{

*/

void Fn1();

void Fn2();

/**

@}

*/

이렇게 사용하면 Fn1, Fn2 가 하나의 그룹으로 묶이고 공통 주석이 달리게 된다.

2.3. 기타 명령

@note

개인적으로 함수나 클래스 설명중 특별히 주의해야 할 점이 있을 경우 사용한다.

다음 명령이 나오기 전까지 모든 내용이 note로 인식된다.

@see

에 대한 see also 가 자동으로 달린다.

특적한 클래스/함수에 대해서 연관된 클래스/함수를 만들 때 유용하다.