developerWorks에 처음 로그인하면 developerWorks프로파일이 생성됩니다.귀하의 프로파일에서 동의하신 내용이 공개되지만 이 사항은 언제든지 변경 가능합니다. 귀하의 성명(숨김으로 체크되어 있어도 표시됩니다)과 디스플레이 이름은 게시한 컨텐츠나 사이트 엑세스시 표시됩니다.

모든 정보가 안전하게 전송되었습니다.

처음 developerWorks에 로그인할 때 프로파일이 작성되므로, 이를 위해 디스플레이 이름을 선택해야 합니다. 선택하신 디스플레이 이름은 developerWorks에 게시한 컨텐츠에 표시됩니다.

3글자 이상 31글자 이하의 길이로 사용 가능합니다. dW커뮤니티 내에서는 보안상 이메일주소를 제외한 다른 이름을 지정하셔야 합니다.

모든 정보가 안전하게 전송되었습니다.

My developerWorks：

나의 통지：

로그아웃

언어 선택：

원시 코드 문서화를 위한 doxygen 익히기

Arpan Sen, 선임 소프트웨어 개발자, Studio B Productions

Arpan은 EDA(Electronic Design Automation) 업계에 몸 담은 소프트웨어 개발자다. 솔라리스, 썬OS, HP-UX, 아이릭스 등과 같은 다양한 유닉스 기종은 물론 리눅스, 마이크로소프트 윈도우까지 다양한 플랫폼을 사용해 왔다. 그의 주된 관심사는 소프트웨어 성능 최적화 기법, 그래프 이론, 병렬 컴퓨팅이다. 기사를 집필하는 이유는 창의적인 욕구를 충족하기 위해서다. Sen은 소프트웨어 시스템 분야에서 대학원 학위를 받았다.

요약： C/C++를 사용해 기존 시스템을 대상으로 진행하는 새로운 기능 추가와 유지보수 작업은 사람 기를 죽입니다. 다행스럽게도 C/C++, 자바(Java™), 파이썬 등을 위한 문서 시스템인 doxygen이 도움이 됩니다. C/C++를 사용한 프로젝트 맥락에서 바라본 doxygen의 기능과 doxygen이 정의한 태그를 활용해 코드를 문서화하는 방법을 살펴봅니다.

여기에 태그 달기!

원문 게재일: 2008 년 10 월 21 일
난이도: 중급
영어로: 보기
페이지뷰： 2232 회
의견：

C/C++로 개발한 기존 시스템을 대상으로 진행하는 새로운 기능 추가와 유지보수 작업은 사람 기를 죽인다. 이런 문제에는 다양한 측면이 있다. 몇 가지 예를 들면, 현존하는 클래스 계층 구조와 전역 변수 이해, 다양한 사용자 정의 유형, 함수 호출 그래프 분석 등이 있다. 이 기사에서는 C/C++ 프로젝트 맥락에서 바라본 몇 가지 예를 사용해 doxygen의 여러 기능을 살펴본다. 하지만 doxygen은 파이썬, 자바, PHP 등과 같은 다른 언어로 개발한 소프트웨어 프로젝트에도 사용하기 충분할 만큼 유연하다. 이 기사를 쓴 동기는 C/C++ 원시 코드에서 정보를 추출하는 데 도움을 주기 위한 목적이지만, doxygen 정의 태그를 사용해 원시 코드를 문서화하는 방법 역시 간략하게 다룬다.

doxygen 설치하기

doxygen을 설치하는 방법은 두 가지다. 미리 컴파일된 실행 파일을 내려받거나 SVN 저장소에서 원시 코드를 체크아웃해 빌드할 수 있다. Listing 1은 직접 빌드하는 과정을 보여준다.

Listing 1. doxygen 원시 코드를 빌드해 설치하기

                
bash-2.05$ svn co https://doxygen.svn.sourceforge.net/svnroot/doxygen/trunk doxygen-svn

bash-2.05$ cd doxygen-svn
bash-2.05$ ./configure --prefix=/home/user1/bin
bash-2.05$ make

bash-2.05$ make install

configure 스크립트는 컴파일된 프로그램을 /home/user1/bin에 설치하도록 지정했다(이 디렉터리를 빌드 후에 PATH 변수에 추가한다). 모든 유닉스(UNIX®) 사용자가 /usr 폴더에 쓰기 권한이 있지 않기 때문이다. 또한 svn 유틸리티를 사용해 원시 코드를 체크아웃할 필요가 있다.

위로

doxygen을 사용한 문서 생성

원시 코드 문서를 생성하기 위해 doxygen을 사용하려면, 다음과 같은 세 단계를 밟는다.

환경 설정 파일 생성

셸 프롬프트에서, doxygen -g 명령을 입력한다. 이 명령은 현재 디렉터리에 Doxyfile이라는 텍스트 형식으로 편집 가능한 환경 설정 파일을 생성한다. 이 파일 이름을 대신해 다른 이름도 지정할 수 있다. Listing 2처럼 doxygen -g <사용자가 정의한 파일 이름> 명령을 내리면 된다.

Listing 2. 기본 환경 설정 파일 생성

                
bash-2.05b$ doxygen -g
Configuration file 'Doxyfile' created.
Now edit the configuration file and enter
  doxygen Doxyfile
to generate the documentation for your project
bash-2.05b$ ls Doxyfile
Doxyfile

환경 설정 파일 편집

환경 설정 파일 구조는 Makefile 형식과 비슷하게 <TAGNAME> = <VALUE>를 바탕으로 한다. 가장 중요한 태그는 다음과 같다.

<OUTPUT_DIRECTORY>: 예를 들어, /home/user1/documentation처럼, 여기에 반드시 생성된 문서 파일이 들어갈 디렉터리 이름을 지정해야 한다. 존재하지 않는 디렉터리 이름을 지정하면, doxygen은 적절한 사용자 접근 허가에 맞춰 디렉터리를 생성한다.
<INPUT>: 이 태그는 생성될 문서 대상인 C/C++ 원시 코드와 헤더 파일이 들어있는 모든 디렉터리 목록을 공백으로 분리해 지정한다. 예를 들어, 다음과 같은 방식으로 지정이 가능하다.
INPUT = /home/user1/project/kernel /home/user1/project/memory
이 경우, doxygen은 지정한 두 디렉터리에서 C/C++ 원시 코드를 읽는다. 프로젝트가 여러 하위 디렉터리를 담은 단일 프로젝트 디렉터리로 구성되어 있다면, 이 폴더를 지정한 다음에 <RECURSIVE> 태그를 Yes로 지정한다.
<FILE_PATTERNS>: 기본으로, doxygen은 .c, .cc, .cpp, .h, .hpp와 같은 전형적인 C/C++ 확장자가 붙은 파일을 찾는다. <FILE_PATTERNS> 태그에 관련된 값을 지정하지 않으면 기본 확장자로 구성된 파일만 찾는다. 원시 코드가 다른 이름 관례를 사용한다면, 이 태그를 여기에 맞춰 바꾼다. 예를 들어, 프로젝트 관례에 따라 C 파일 확장자를 .c86로 지정했다면, 이 확장자를 <FILE_PATTERNS> 태그에 추가한다.
<RECURSIVE>: 원시 코드 계층이 중첩되어 있고 모든 계층에 존재하는 C/C++ 파일을 위한 문서를 생성할 필요가 있을 때, 이 태그를 Yes로 설정한다. 예를 들어, 프로젝트 루트 디렉터리가 /home/user1/project/kernel이며, /home/user1/project/kernel/vmm, /home/user1/project/kernel/asm과 같은 하위 디렉터리가 여러 개 있을 때를 생각해보자. 이 태그를 Yes로 설정하면, doxygen은 계층을 탐색하며 정보를 추출한다.
<EXTRACT_ALL>: 이 태그는 개별 클래스나 함수에 문서화가 되어 있지 않은 경우에도 문서를 끄집어 내도록 doxygen에 지시한다. 이 태그를 반드시 Yes로 지정해야 한다.
<EXTRACT_PRIVATE>: 이 태그를 Yes로 지정한다. 그렇지 않으면 클래스의 private 자료 멤버가 문서화에서 빠진다.
<EXTRACT_STATIC>: 이 태그를 Yes로 지정한다. 그렇지 않으면, 파일의 정적 멤버(함수나 변수 모두)가 문서화에서 빠진다.

Listing 3은 Doxyfile의 예를 보여준다.

Listing 3. 사용자가 정의한 태그 값이 들어있는 doxyfile 예제

                
OUTPUT_DIRECTORY = /home/user1/docs
EXTRACT_ALL = yes
EXTRACT_PRIVATE = yes
EXTRACT_STATIC = yes
INPUT = /home/user1/project/kernel
# 필요하지 않다면 아무 확장자도 추가하지 말라. doxygen은 이미
#.c/.cc/.cxx/.c++/.cpp/.inl/.h/.hpp와 같은 공통 확장자를 이해하고 있다.
FILE_PATTERNS = 
RECURSIVE = yes

doxygen 실행

셸 프롬프트에서 doxygen Doxyfile 명령을 내려 doxygen을 실행한다(여기서 환경 설정 파일 이름을 각자 지정한 이름으로 바꾼다). Doxygen은 최종적으로 HTML(Hypertext Markup Language)과 LaTeX 형식(기본값)으로 문서를 만들어내기 앞서 몇 가지 메시지를 출력한다. <OUTPUT_DIRECTORY> 태그가 지정하는 폴더에, 문서 생성 과정의 일부로 html과 latex이라는 두 하위 폴더가 만들어진다. Listing 4는 간단한 doxygen 동작 로그를 보여준다.

Listing 4. doxygen 로그 출력 예

                
Searching for include files...
Searching for example files...
Searching for images...
Searching for dot files...
Searching for files to exclude
Reading input files...
Reading and parsing tag files
Preprocessing /home/user1/project/kernel/kernel.h
...
Read 12489207 bytes
Parsing input...
Parsing file /project/user1/project/kernel/epico.cxx
...
Freeing input...
Building group list...
..
Generating docs for compound MemoryManager::ProcessSpec
...
Generating docs for namespace std
Generating group index...
Generating example index...
Generating file member index...
Generating namespace member index...
Generating page index...
Generating graph info page...
Generating search index...
Generating style sheet...

위로

문서 출력 형식

Doxygen은 HTML 이외에 다른 몇 가지 출력 형식에 맞춰 문서를 생성할 수 있다. 다음에 소개하는 형식으로 문서를 생성하도록 doxygen의 환경을 설정할 수 있다.

유닉스 매뉴얼 페이지: <GENERATE_MAN> 태그를 Yes로 설정하자. 기본적으로 <OUTPUT_DIRECTORY>를 사용해 지정한 디렉터리 내부에 man이라는 하위 폴더가 생성되며, 이 폴더 안에 만들어진 문서가 들어간다. MANPATH 환경 설정 변수에 이 폴더를 추가하자.
RTF(Rich Text Format): <GENERATE_RTF> 태그를 Yes로 설정하자. 생성될 .rtf 파일 위치를 지정하려면 <RTF_OUTPUT>을 설정한다. 기본적으로 이 문서는 <OUTPUT_DIRECTORY>를 사용해 지정한 디렉터리 내부에 rtf라는 하위 폴더가 생성된다. 여러 문서를 탐색하려면, <RTF_HYPERLINKS>를 Yes로 설정한다. 이렇게 설정하면, 생성된 .rtf 파일은 교차 탐색을 위한 링크를 포함한다.
LaTeX: 기본적으로, doxygen은 LaTeX과 HTML 형식으로 문서를 생성한다. <GENERATE_LATEX> 태그는 Doxyfile에서 Yes로 기본 설정되어 있다. 또한 <LATEX_OUTPUT> 태그는 latex으로 설정되어 있기에 <OUTPUT_DIRECTORY>를 사용해 지정한 디렉터리 내부에 latex이라는 폴더가 생성되며, 이 폴더 안에 만들어진 문서가 들어간다.
CHM(Microsoft® Compiled HTML Help): <GENERATE_HTMLHELP> 태그를 Yes로 설정하자. 이 형식은 유닉스 플랫폼에서 지원하지 않으므로, doxygen은 HTML 파일을 보관하는 동일 폴더에 index.hhp라는 파일만 생성한다. 실제 .chm 파일을 만들어내려면 HTML help 컴파일러를 사용해 이 파일을 컴파일해야 한다.
XML(Extensible Markup Language): <GENERATE_XML> 태그를 Yes로 설정하자(XML 출력은 doxygen 팀에서 계속해서 작업 중이라는 사실을 기억하자).

Listing 5는 여기서 설명한 모든 형식으로 문서를 만들도록 설정한 Doxyfile 예다.

Listing 5. 여러 형식으로 문서를 만들기 위한 Doxyfile 예

                
#for HTML 
GENERATE_HTML = YES
HTML_FILE_EXTENSION = .htm

#for CHM files
GENERATE_HTMLHELP = YES

#for Latex output
GENERATE_LATEX = YES
LATEX_OUTPUT = latex

#for RTF
GENERATE_RTF = YES
RTF_OUTPUT = rtf 
RTF_HYPERLINKS = YES

#for MAN pages
GENERATE_MAN = YES
MAN_OUTPUT = man
#for XML
GENERATE_XML = YES

위로

doxygen에서 사용하는 특수 태그

Doxygen은 몇 가지 특수 태그를 포함한다.

C/C++ 코드 선행처리

우선, doxygen은 정보를 추출하기 위해 C/C++ 코드를 선행처리해야 한다. 하지만 기본적으로, 이런 작업은 일부 선행처리만 가능하다. 즉, 조건 컴파일 구문(#if...#endif)을 평가하지만 매크로 확장은 수행하지 않는다. Listing 6에 있는 코드를 살펴보자.

Listing 6. 매크로를 사용하는 C++ 코드 예제

                
#include <cstring>
#include <rope>

#define USE_ROPE

#ifdef USE_ROPE
  #define STRING std::rope
#else
  #define STRING std::string
#endif

static STRING name;

원시 코드에 <USE_ROPE>를 정의할 경우 doxygen이 생성한 문서는 다음과 같다.

                Defines
    #define USE_ROPE
    #define STRING std::rope

Variables
    static STRING name

여기서, doxygen이 조건부 컴파일을 수행했지만, STRING에 대한 매크로 확장은 수행하지 않았음을 확인할 수 있다. Doxyfile에서 <ENABLE_PREPROCESSING> 태그는 기본적으로 Yes로 설정되어 있다. 매크로 확장을 허용하려면, <MACRO_EXPANSION> 태그 역시 Yes로 설정해야 한다. 이렇게 해서 만들어진 doxygen 결과는 다음과 같다.

                Defines
   #define USE_ROPE
    #define STRING std::string

Variables
    static std::rope name

<ENABLE_PREPROCESSING> 태그를 No로 설정하면, doxygen 출력은 다음과 같다.

                Variables
    static STRING name

문서에 정의가 없으므로, STRING 타입을 추론할 방법이 없다. 따라서 <ENABLE_PREPROCESSING> 태그를 항상 Yes로 설정하는 방식이 의미가 있다.

문서화 작업의 일부로, 단순히 특정 매크로만 확장하는 편이 바람직한 경우가 있다. 이런 목적을 위해, <ENABLE_PREPROCESSING>과 <MACRO_EXPANSION>을 Yes로 설정하는 동시에 <EXPAND_ONLY_PREDEF> 태그를 Yes로 설정한다(이 태그는 기본적으로 No로 설정되어 있다). 그러고 나서 <PREDEFINED>나 <EXPAND_AS_DEFINED> 태그에서 매크로 세부 내역을 지정한다. Listing 7에 있는 코드를 살펴보면, CONTAINER 매크로만 확장된다.

Listing 7. 다중 매크로가 들어있는 C++ 원시 코드

                
#ifdef USE_ROPE
  #define STRING std::rope
#else
  #define STRING std::string
#endif

#if ALLOW_RANDOM_ACCESS == 1
  #define CONTAINER std::vector
#else
  #define CONTAINER std::list
#endif

static STRING name;
static CONTAINER gList;

Listing 8은 환경 설정 파일을 보여준다.

Listing 8. 매크로 확장을 선택하도록 만든 Doxyfile

                
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
EXPAND_AS_DEFINED = CONTAINER
...

여기서 CONTAINER만 확장된 doxygen 결과를 볼 수 있다.

                Defines
#define STRING   std::string 
#define CONTAINER   std::list

Variables
static STRING name
static std::list gList

CONTAINER 매크로만 확장되었음에 주목하자. <MACRO_EXPANSION>과 <EXPAND_ONLY_PREDEF>를 둘 다 Yes로 지정해 놓으면, <EXPAND_AS_DEFINED> 태그는 등호 연산자의 오른쪽에 열거된 매크로만 확장한다.

선행처리 과정의 일부로, 주목할 최종 태그는 <PREDEFINED>다. g++ 컴파일러 선행처리 정의에 넘기는 -D 스위치 활용과 비슷한 방식으로 이 태그를 사용해 매크로를 정의한다. Listing 9에 나온 Doxyfile을 살펴보자.

Listing 9. 매크로 확장 태그를 정의한 Doxyfile

                
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
EXPAND_AS_DEFINED = 
PREDEFINED = USE_ROPE= \
                             ALLOW_RANDOM_ACCESS=1

doxygen이 생성한 결과는 다음과 같다.

                Defines
#define USE_CROPE 
#define STRING   std::rope 
#define CONTAINER   std::vector

Variables
static std::rope name 
static std::vector gList

<PREDEFINED> 태그를 사용할 때, 매크로는 <macro name>=<value> 형태로 정의해야 한다. 단순 #define 정의처럼 값을 넣지 않으려면, <macro name>=<spaces>로 지정한다. 다중 매크로 정의는 공백이나 역슬래시(\)로 구분한다.

문서화 과정에서 특정 파일이나 디렉터리 배제하기

문서 생성 과정에서 배제해야 하는 파일과 디렉터리 이름을 Doxyfile 내부에 정의한 <EXCLUDE> 태그에 공백으로 분리해 추가한다. 이는 프로젝트 루트 디렉터리를 추가한 다음에 몇몇 하위 디렉터리만 건너 뛰도록 간편하게 정의하는 경우에 유용하다. 예를 들어, 프로젝트 루트 디렉터리가 src_root이며, examples/와 test/memoryleaks 폴더를 문서화 과정에서 건너뛰도록 만들기를 원하면, Doxyfile을 Listing 10처럼 구성한다.

Listing 10. EXCLUDE 태그를 사용하는 Doxyfile

                
INPUT = /home/user1/src_root
EXCLUDE = /home/user1/src_root/examples /home/user1/src_root/test/memoryleaks
...

위로

그래프와 다이어그램 생성하기

기본적으로 Doxyfile에는 <CLASS_DIAGRAMS> 태그를 Yes로 설정해 놓았다. 이 태그는 클래스 계층 다이어그램 생성에 사용된다. 좀 더 나은 모양으로 출력하려면 Graphviz 다운로드 사이트에서 dot 도구를 내려받는다. Doxyfile에서 다음 태그는 다이어그램 생성과 관련이 있다.

<CLASS_DIAGRAMS>: Doxyfile에서 이 태그는 기본적으로 Yes로 설정되어 있다. 이 태그를 No로 설정하면, 상속 계층을 보여주는 다이어그램이 생성되지 않는다.
<HAVE_DOT>: 이 태그를 Yes로 설정하면, doxygen은 dot 도구를 사용해서 좀 더 강력한 그래프를 생성한다. 예를 들어, 개별 클래스 멤버와 자료 구조를 이해하는 데 도움을 주는 협력 다이어그램을 그려준다. 이 태그를 Yes로 설정하면, <CLASS_DIAGRAMS> 태그 효과를 무효로 한다는 사실을 기억하자.
<CLASS_GRAPH>: <HAVE_DOT> 태그와 더불어 이 태그를 Yes로 설정하면, 상속 계층 다이어그램을 dot 도구를 사용해 생성하며, <CLASS_DIAGRAMS>만 사용해 그린 경우보다 훨씬 더 멋진 외형과 느낌을 제공한다.
<COLLABORATION_GRAPH>: <HAVE_DOT> 태그와 더불어 이 태그를 Yes로 설정하면, doxygen은 (상속 다이어그램과는 별개로) 개별 클래스 멤버(포함 관계)와 상속 계층을 보여주는 협력 다이어그램을 생성한다.

Listing 11은 몇몇 자료 구조를 사용한 예다. <HAVE_DOT>, <CLASS_GRAPH>, <COLLABORATION_GRAPH> 태그를 환경 설정 파일에서 모두 Yes로 설정했다.

Listing 11. C++ 클래스와 구조 사이 관계

                
struct D {
  int d;
};

class A {
  int a;
};

class B : public A {
  int b;
};

class C : public B {
  int c;
  D d;
};

그림 1은 doxygen이 생성한 결과를 보여준다.

그림 1. dot 도구를 사용해 생성한 클래스 상속 그래프와 협력 그래프

위로

코드 문서화 스타일

지금까지, doxygen이 없었더라면 문서화되지 않은 상태로 남아 있었을 코드에서 정보를 추출하기 위해 doxygen을 사용해왔다. 하지만 doxygen은 또한 문서 스타일과 구문을 중요하게 여기며, 좀 더 세부적인 문서를 생성하는 데 도움을 준다.이 절은 C/C++ 코드 일부를 사용해 doxygen이 중요하게 여기는 좀 더 공통 태그 몇 가지를 설명한다. 세부 사항은 참고자료를 참조하자.

개별 코드 구성 요소에는 간략한 설명과 세부 설명이라는 두 가지 설명 유형이 있다. 간략한 설명은 일반적으로 한 행으로 끝난다. 함수와 클래스 메서드에는 본문 설명이라는 설명 방법이 별도로 존재하며, 함수 본문 내에서 나타나는 모든 주석 블록을 결합한 형태다. 몇 가지 추가 doxygen 태그와 주석 스타일은 다음과 같다.

간략한 설명: C++의 // 주석을 사용하거나 <\brief> 태그를 사용한다.
세부 설명: JavaDoc 스타일의 주석인 /** ... test ... */(처음에 나오는 별 두 개[*]에 주의하자)나 Qt 스타일의 /*! ... text ... */를 사용한다.
본문 설명: 클래스, 구조체, 유니언, 이름 공간과 같은 개별 C++ 구성 요소마다 <\class>, <\struct>, <\union>, <\namespace>라는 태그가 존재한다.

전역 함수, 변수, enum 유형을 문서화하려면, 대응하는 파일은 우선 <\file> 태그를 사용해 문서를 만들어야 한다. Listing 12는 함수 태그(<\fn>), 함수 인수 태그(<\param>), 변수 이름 태그(<\var>), #define을 위한 태그(<\def>), 코드 조각에 관련된 몇 가지 구체적인 쟁점을 지시하는 태그(<\warning>)를 소개하는 예를 보여준다.

Listing 12. 전형적인 doxygen 태그와 활용법

                
/*! \file globaldecls.h
      \brief 전역 변수, enum, 함수와 매크로 정의를 담고 있다.
  */

/** \var const int fileSize
      \brief 디스크에 있는 파일 기본 크기
  */
const int fileSize = 1048576;

/** \def SHIFT(value, length)
      \brief 왼쪽 비트 시프트 값과 길이
  */
#define SHIFT(value, length) ((value) << (length))

/** \fn bool check_for_io_errors(FILE* fp)
      \brief 파일 손상을 점검
      \param fp 이미 열린 파일을 가리키는 포인터
      \warning 스레드 안전하지 않다!
  */
bool check_for_io_errors(FILE* fp);

여기서 생성된 문서를 정리하면 다음과 같다.

                Defines
#define SHIFT(value, length)   ((value) << (length))  
             왼쪽 비트 시프트 값과 길이

Functions
bool check_for_io_errors (FILE *fp)  
        파일 손상을 점검

Variables
const int fileSize = 1048576;
Function Documentation
bool check_for_io_errors (FILE* fp)
파일 손상을 점검

Parameters
              fp: 이미 열린 파일을 가리키는 포인터

Warning
스레드 안전하지 않다!

위로

결론

이 기사는 기존 C/C++ 코드에서 doxygen이 상당수 유효한 정보를 추출하는 방법을 설명했다. doxygen 태그를 사용해 코드를 문서화하면, doxygen은 읽기 쉬운 형식으로 출력물을 생성한다. 제대로 사용하면 doxygen은 개발자가 기존 시스템을 유지보수하고 관리하기 쉽도록 만들어주는 훌륭한 도구가 될 것이다.

참고자료

교육