Doxygen

Doxygen 는 C++, C, Java, IDL (Corba, Microsoft, and KDE-DCOP flavors), PHP, C# 을 위한 문서화 시스템이다.

source 에 남기는 주석을 이용하여 HTML, LaTex, RTF 포맷의 문서를 출력할 수 있다.

다운로드 및 설치

Doxygen

Doxygen site 에서 platform에 맞는 버전을 다운 받는다.

Graphviz

Doxygen 에서 document를 생성할 때 class 계층도나 파일 관계도를 그림으로 만들기 위해서 필요하다.

Graphviz site 에서 platform에 맞는 버전을 다운 받는다.

Html Help Workshop

Doxygen으로 생성한 html을 CHM 으로 만들기 위해서 Microsoft HTML Help Workshop 를 다운받는다.

DoxBar

Developer Studio 에서 Doxygen을 손쉽게 사용할 수 있는 add-on 모듈.

doxbar site 에서 다운 받을 수 있다.

설치는 doxbar site의 설명을 따라가면 된다.

간단한 주석 규칙

주석을 달때 몇가지 style 이 적용되지만 나는 javadoc 스타일을 선호한다. 아래 내용 이외에도 history, todo 에 관한 규칙도 있지만 따로 설명하지 않는다.

파일에 대한 주석

/**	@file [파일명]
	@brief [파일에 대한 간단한 설명]
*/

/*/////////////////////////////////////////////////////////////////////////////
// Include Headers
*/

/*/////////////////////////////////////////////////////////////////////////////
// Constants
*/

/*/////////////////////////////////////////////////////////////////////////////
// Declare Types
*/

/*/////////////////////////////////////////////////////////////////////////////
// Global Variable
*/

/*/////////////////////////////////////////////////////////////////////////////
// Declare Functions
*/

/*/////////////////////////////////////////////////////////////////////////////
// Implementation
*/

/*/////////////////////////////////////////////////////////////////////////////
// End of file
*/

함수에 대한 주석

/**	@brief [함수에 대한 간단한 설명]

	@param[in] [파라미터 설명]
	@param[out] [파라미터 설명]
	@param[in,out] [파라미터 설명]

	@return [Return Values]

	@remark [Remarks]

	@sa [See Also]

	@note [Note]
*/
int hello(int x)
{
...
}

class에 관한 주석

/**	@brief [class 에 대한 간단한 설명]
*/
class Foo
{
...
};

struct에 관한 주석

/**	@brief [struct 에 대한 간단한 설명]
*/
struct foo
{
...
};

class, struct 멤버 변수, 일반 변수에 관한 주석

int i;	/**< loop counter */

매크로에 관한 주석

/**	@brief [macro 설명]
*/
#define FOO(x)   do { ... } while (0)

Group

/// @defgroup GROUPNAME description
//@{

/** @defgroup SUBGROUP1 desc
@ingroup GROUPNAME
*/
//@{
...
//@}

/// @name group name
//@{
...
//@}

//@}

유용한 plugin

DoxygenToolkit

VIM용 plugin. 함수 주석을 편리하게 달 수 있다.

아래는 내 vimrc에서 DoxygenToolkit용 설정

"for DoxygenToolkit.vim
let g:DoxygenToolkit_interCommentTag="^I"
let g:DoxygenToolkit_blockHeader=""
let g:DoxygenToolkit_blockFooter="^I@warning^I^M^M^I@remarks^I^M^M^I@note^I^M^M^I@sa^I^M"
let g:DoxygenToolkit_authorName="Yun-yong Choi"

실제 설정에 적용할때는 ^I는 tab을 누르면 되고 ^M은 ^V를 누르고 엔터키를 누르면 된다.

플러그인은 http://www.vim.org/scripts/script.php?script_id=987 에서 받을 수 있다.