Doxygen 사용을 위한 주석

지금 개발 중인 프로그램의 문서화가 필요해서 doxygen을 한번 사용해봤다. 지금까지는 doxygen을 사용하려면 doxygen 타입의 주석이 꼭 있어야만 가능한줄 알고 있었는데 그게 아니더군. 일단 데이터 구조와 파일들을 분리해서 문서화 해주는건 꼭 doxygen 타입의 주석이 없더라도 가능(EXTRACT_ALL 옵션 YES)하다.

하지만 내가 달아놓은 주석이 생성된 문서에 제대로 포함되지가 않는다. 지금까지 JavaDoc 스타일을 어정쩡하게 변경해서 사용했는데 이게 doxygen에 의해 제대로 처리가 안되더군. 그래서 앞으로는 아래와 같이 주석을 달아서 doxygen을 사용해 보도록 하자.

/* $Id: support.c,v 1.1.1.1.2.16 2007/04/20 01:08:50 superkkt Exp $ */
/* Copyright 2007 Samjung Data Service, Inc. All rights reserved. */

/**
* @file support.c
* @brief 유리틸리 함수 모듈
* @author 김기태 (superkkt@email.co.kr)
* @defgroup support_module 유틸리티 함수 모듈
* 여러가지 유틸리티 함수들을 모아놓은 모듈
* @{
*/

#ifdef HAVE_CONFIG_H
#include <config.h>
#endif

#include <stdio.h>
#include <errno.h>

/**
* TAR 버퍼 구조체
*/
typedef struct
{
   off_t total; /**< 버퍼에 있는 총 데이터 사이즈 */
   off_t cur_offset; /**< 현재 오프셋 */
   unsigned char buf[INTERNAL_BUF]; /**< 내부 버퍼 */
} TAR_BUF;

/**
* 시스템 인코딩에서 UTF-8로 문자열 변환한다. 설정파일에 저장된 인코딩이 UTF-8
* 이라면 변환 없이 새로 할당된 동적 메모리에 문자열을 복사하고 성공을 리턴한다.
*
* @param str - 변환할 문자
* @param ptr - UTF-8로 문자열이 저장된 메모리 포인터
* @return 성공 시 0, 실패 시 -1
* @warning \a ptr 은 호출자가 사용 후 FREE() 함수를 통해 메모리를 해제해야 한다.
* @todo 시스템 인코딩을 알 수 없는 경우 예외 처리를 추가한다.
* @bug 설정파일에 지정된 인코딩이 EUC-JP인 경우 오류가 발생한다.
*/
int
encode_str_to_utf8(const char *str, char **ptr)
{
...
}

/**
* @}
* End of support_module
*/

위에서 사용된 doxygen 타입 주석을 간단하게 살펴보자. 두개의 *와 <를 사용해서 구조체나 공용체의 멤버 변수에 대한 주석을 표시한다.

/**< 버퍼에 있는 총 데이터 사이즈 */

@defgroup 지시자를 통해서 특정 내용을 모듈로 표현할 수 있다. 보통 모듈별로 파일을 분할해서 코딩을 하기 때문에 아래와 같이 파일의 처음과 끝에 @defgroup 지시자를 사용하면 된다.

/**
* @defgroup module_name short_description
* detail_description
* @{
*/
...
... 실제 파일 내용 ...
...
/**
* @}
* End of module_name
*/

\a 지시자는 뒤에오는 문자열을 이탤릭체로 표시해준다. 주로 함수의 파라메터 이름을 표현할때 사용한다. \n 지시자는 줄바꿈 문자이다. 주석에서는 엔터로 줄바꿈을 했더라도 doxygen에 의해 생성된 HTML에서는 줄바꿈이 안되어있다. 따라서 \n 지시자를 사용해서 명시적으로 줄바꿈을 해줘야 한다.

그리고 위와 같이 JavaDoc 스타일로 된 주석을 doxygen이 처리하게 하려면 JAVADOC_AUTOBRIEF 옵션이 YES로 되어있어야 한다.

@todo와 @bug 지시자를 사용하면 Doxygen 산출물의 최상단 메뉴에 Related Page라는 메뉴가 생기고 거기에 TODO LIST와 BUG LIST가 추가된다.

Doxygen으로 생성된 메인 페이지에 기록 할 내용은 아래와 같이 소스 파일상에 주석으로 남겨두면 된다.

/**
* @mainpage Direct Backup System
* @section intro 개요
* Direct Backup System(이하 DBS)은 웹기반의 사용자 인터페이스를 제공하는 백업
* 시스템이다.\n어쩌고 저쩌고... 테스트..
*
* @section features 특징
* @subsection platform 지원 플랫폼
* 솔라리스
* 리눅스
* 윈도우 (Experimental)
* @subsection etc 기타
* 다양한 캐릭터셋 지원 (내부적으로는 UTF-8 사용)\n
* 어쩌고 저쩌고.. 테스트..
*/

* 간단한 사용법

1. 템플릿 설정파일 생성

# doxygen -g

2. 템플릿 수정

PROJECT_NAME = DBS
OUTPUT_DIRECTORY = ./doxygen
OUTPUT_LANGUAGE = English
JAVADOC_AUTOBRIE = YES
OPTIMIZE_OUTPUT_FOR_C = YES
EXTRACT_ALL = YES
EXTRACT_STATIC = YES
INPUT = /home/superkkt/work/dbs_v3
RECURSIVE = YES

3. 인코딩 설정

Doxygen에서는 언어를 한글로 설정할 경우 생성되는 HTML 파일의 인코딩이 EUC-KR로 된다. 설정 파일을 찾아봐도 인코딩을 바꾸는건 찾지 못하겠고 임시 방편으로 HTML_HEADER 옵션에 파일 이름을 지정해서 해당 파일 내용을 생성되는 HTML의 헤더로 사용하도록 했다. 우선 HTML_HEADER 옵션을 지정하지 않은 상태에서 doxygen을 실행하고 생성된 결과 페이지의 소스에서 <head>와 </head>의 사이에 있는 내용을 복사해서 파일로 저장하고 인코딩을 UTF-8로 바꿔준다.

[superkkt@backup1 dbs_0.9]$ cat doxygen_header
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
<title>DBS: Data Structures</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
<link href="tabs.css" rel="stylesheet" type="text/css">

그리고나서 설정파일에서 위 파일을 HTML_HEADER로 지정해준다.

HTML_HEADER = doxygen_header

이제 다시 doxygen을 실행해서 결과를 생성하면 된다. 단, 이 경우 언어를 Korean으로 할경우 메뉴에 있는 글자들이 EUC-KR로 만들어져있기 때문에 한글이 다 깨진다. 따라서 어쩔수 없이 언어를 영어로 설정해야만 한다.

4. Caller graph 그리기

dot tool이 설치되어 있고 설정파일에서 Caller Graph를 그리도록 설정되어 있으면 global 함수의 경우(메뉴얼에는 global만 된다고 나와있지만 실제로는 static 함수도 그래프가 그려짐) 어떤 함수에 의해 호출되는지 그래프를 그려준다. 그래프의 종류에는 call graph, caller graph, include graph, include by graph 등이 있는데, 사용해보고 상황에 따라 적절한 그래프만 선택적으로 사용하는게 좋다.

HAVE_DOT = YES
INCLUDE_GRAPH = NO
INCLUDED_BY_GRAPH = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES

Superkkt Blog