메뉴 건너뛰기


Developer > Development Tools

Doxygen 4장. Doxygen 응용 1/3

2013.11.16 01:36

푸우 조회 수:10301

  http://www.stack.nl/~dimitri/doxygen/manual.html
  http://www.stack.nl/~dimitri/doxygen/commands.html

1.jpg

 
이번에는 가상 프로젝트를 하나 만들고 Doxygen을 실제로 사용하는 방법에 대해서 알아보도록 하겠습니다.
 
 
4장. Doxygen 응용 1/3
 
여기서 말하는 문법이란? 주석을 문서화 하기 위한 문법이라는거 알고 계시겠죠?
우선 Doxygen에서 인식하는 주석의 종류를 알아볼까요?
 
1. Doxygen에서 인식하는 주석 형식
 
Doxygen은 JavaDoc 스타일과 Qt스타일 두가지를 지원합니다.
다음은 JavaDoc 스타일과 Qt스타일 두가지에 대한 비교입니다.
 

JavaDoc Style

Qt Style

Block Comment
/**
 * 간단한 설명.
 * 상세한 설명
 * @param num 파라메터입니다.
 * @return 성공이면 0 실패면 -1을 리턴
 */ 
/*!
 * \brief 간단한 설명
 *
 * 상세한 설명
 * \param num 파라메터입니다.
 * \return 성공이면 0 실패면 -1을 리턴
 */
 
또는
 
/*!
 \brief 간단한 설명
 
 상세한 설명
 \param num 파라메터입니다.
 \return 성공이면 0 실패면 -1을 리턴
 */
Line Comment
/// 한 라인에 대한 커맨트입니다.
//! 한 라인에 대한 커맨트입니다.
//!< 이것은 필드(구조체, 클래스, 함수매개변수 등)에 다는 주석
///< 이것은 필드(구조체, 클래스, 함수매개변수 등)에 다는 주석
 
 
블록 주석에서 JavaDoc 스타일의 경우 주석의 시작이 /** 로 *이 두번 있다는 것이 특이한 점이구요.
Qt스타일에서는 /*! 와 같이 생긴 것이 특이한 점이네요.
블록 주석에서는 간단하게 내용을 설명하는 부분과 상세하게 설명하는 부분으로 나뉘는데...
JavaDoc 스타일의 경우 주석의 제일 첫 문장(마침표 다음에 줄바꿈이 된)을 간단하게 내용을 설명하는 부분으로 간주하구요. Qt스타일에서는 "\brief"라는 명령뒤에 쓴 글부터 시작해서 빈라인이 오는 곳 까지를 간단한 설명으로 취급합니다. 하지만 JavaDoc스타일을 사용한다고 해도 \brief를 사용해야 합니다. 만약 이게 불편하다고 생각하면 Doxyfile의 환경변수의 JAVADOC_AUTOBRIEF 항목이나 QT_AUTOBRIEF항목을 YES로 하면 \brief나 @brief를 사용하지 않아도 첫번째 라인의 마침표가 올대까지의 문장을 간단한 설명문으로 사용할 수 있습니다.
 
다른 부분과 구분하기 위해 다음과 같이 주석을 달 수도 있습니다.
 
 또는
 
/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////
 
그런데 Doxygen은 JavaDoc과 Qt스타일을 섞어서 사용해도 모두 인식합니다.
우리나라에서는 Java사용자가 많기 때문인지 JavaDoc스타일로 사용하는 예가 많습니다. 또 다른 이유로는 \가 한글환경에서 그리 예쁘게 보이지 않아 @를 사용하는 추세인것 같습니다.
 
그래서 이 글에서도 추세를 따라서 설명하도록 하겠습니다.
 
 
2. 프로젝트 생성하기
 
앞으로의 설명을 위해 가상의 프로젝트를 만들고 Doxyfile의 환경을 위선 설정해 보도록 하겠습니다.
여기서는 프로젝트를 설명하고자 하는게 아니니 그냥 소스가 돌아가든 안 돌아가든 주석을 다는 법을 위주로 설명하도록 하겠습니다. 우선 프로젝트는 간단히 사용자에게 파라메터를 입력받아 "Hello <파라메터>"를 출력하는 프로그램입니다. 미리 이야기 하지만 설명을 위해 사용하지도 않는 함수를 만들기도 하고 쓸때 없는 주석도 달 것입니다. 오해 없으시길....
우선 디렉토리 구성은 다음과 같이 만드세요.
2.png
 
저는 D:\Work\hello_doxygen 폴더에 위와 같이 만들었습니다.
예상하다시피 src폴더는 소스파일(*.c 혹은 *.cpp), include폴더는 헤더파일(*.h), res폴더는 그냥 리소스 파일들을 모아 놓는 폴더인데 여기서는 html 문서를 만들때 사용할 이미지를 넣어 두기로 하겠습니다. doc폴더는 실제 문서화한 결과가 들어갈 폴더이구요. example 폴더는 소스의 사용예를 담아 둘 폴더입니다.
res 폴더에 여러분이 좋아하는 이미지(*.jpg 혹은 *.png 혹은 *.gif)파일을 하나 넣어 두세요.
저는 첨부한 이미지 파일(pooh.jpg)을 넣어 놓겠습니다.
그리고 다음과 같은 소스파일을 hello.cpp라는 이름으로 src폴더에 넣으세요. 
 
#include &lt;string.h&gt; #include &lt;malloc.h&gt; #include &lt;iostream.h&gt; #include "./include/hello.h" Hello::Hello(char *user) { this-&gt;username=NULL; this-&gt;count=0; this-&gt;username=strdup(user); } Hello::~Hello(void) { if(this-&gt;username) free(this-&gt;username); } char *Hello::getUserName(void) { return this-&gt;username; } void Hello::setCount(int num) { this-&gt;count=num; } int Hello::getCount(void) { return this-&gt;count; } void Usage(void) { cout &lt;&lt; "Usage: hello_doxygen &lt;username&gt;\n"; } int main(int argc, char *argv[]) { if(argc&lt;2) { Usage(); return -1; } Hello *hObj=new Hello(argv[1]); cout &lt;&lt; hObj-&gt;getUserName() &lt;&lt; "\n"; delete hObj; return 0; }
 
그리고 include 폴더에 다음과 같은 헤더 파일을 hello.h라는 이름으로 include폴더에 넣으세요.
 
class Hello { private: char *username; public: int count; public: Hello(char *user); ~Hello(void); char *getUserName(void); void setCount(int num); int getCount(void); };
 
그리고 Command창을 열어 src 폴더로 이동하세요. 그리고 다음과 같은 명령을 실행합니다.
물론 doxygen을 설치한 곳이 Path에 걸려 있다는 가정하에서 하는 이야기 입니다. 걸려 있지 않다면 전체 경로를 사용해야 한다는 것을 아시죠? 
 
C:\Work\hello_doxygen\src&gt;doxygen -g Configuration file `Doxyfile' created. Now edit the configuration file and enter doxygen Doxyfile to generate the documentation for your project
 
위의 명령을 실행하면 Doxyfile이라는 doxygen 환경파일이 생성됩니다. 
 
Doxyfile을 열어서 다음의 항목을 찾아 설정된 값으로 바꾸세요.
나머지 부분은 기본값 그대로 두세요.
 
PROJECT_NAME = "Hello Projects" PROJECT_NUMBER = 1.0 OUTPUT_DIRECTORY = ../doc/ OUTPUT_LANGUAGE = Korean JAVADOC_AUTOBRIEF = YES TAB_SIZE = 4 OPTIMIZE_OUTPUT_FOR_C = YES EXTRACT_ALL = YES INPUT = . INPUT_ENCODING = CP949 EXAMPLE_PATH = ../example/ IMAGE_PATH = ../res/ SOURCE_BROWSER = YES GENERATE_HTMLHELP = YES CHM_FILE = hello.chm HHC_LOCATION = "C:\Program Files\HTML Help Workshop\hhc.exe" GENERATE_TREEVIEW = YES GENERATE_LATEX = NO HAVE_DOT = YES CALL_GRAPH = YES CALLER_GRAPH = YES DOT_PATH = "C:\Program Files\Graphviz-2.14\bin"
 
이제 하나하나씩 해 보도록 하겠습니다. 
 
 
3. MainPage 만들기
 
프로젝트를 생성하여 이를 문서화하였을 때 첫 페이지를 MainPage라고 합니다. MainPage는 좀 특수하게 여겨집니다.  뭐 메인페이지는 하나밖에 없으니깐 그렇겠죠?
메인페이지를 만들기 위한 내용을 일반 소스 파일(hello.cpp)에 넣을 수도 있지만 소스에 같이 두면 지저분해 지니깐... 따로 만들도록 하겠습니다.
src폴더에서 다음과 같은 파일을 만들어 mainpage.dox 라는 이름으로 저장하세요.
 
/** @mainpage 헬로 프로젝트 헬로 프로젝트는 Doxygen을 테스트하기 위해 만드는 프로젝트입니다. @section INTRO - 소개 : Doxygen강좌에 사용하기 위해 제작해 보는 프로젝트입니다. @section PROGRAM 프로그램명 - 프로그램명 : Hello 프로그램. @section INOUTPUT 입출력자료 - INPUT : 당신의 이름. - OUTPUT : Hello &lt;당신의 이름&gt;을 화면에 출력. @section CREATEINFO 작성정보 - 작성자 : nicklib - 작성일 : 2007/10/23 @section ADDINFO 추가정보 - 1레벨 인덴트 - 2레벨 인덴트(탭으로 들여쓸경우 하위 항목이 된다.) - 3레벨 인덴트(3레벨 이상은 글머리 기호는 바뀌지 않고 인덴트만 이루어 진다.) -# 번호매기기는 '-#' 방식으로 할수 있다. -# 2레벨 번호매기기 1 -# 2레벨 번호매기기 2 -# 3레벨 번호매기기 1 -# 3레벨 번호매기기 2 -# 4레벨 번호매기기 1 -# 4레벨 번호매기기 2 (4레벨 이상은 1레벨 번호와 같이 보여짐) -# 두번째 하위 항목 @section Links 참고페이지 - @ref HowMakePages "새로운 페이지 만드는 방법"\n - @ref 야후: http://www.yahoo.co.kr @image html pooh.jpg "비오는 날의 푸우" */
 
자 이번에는 page.dox 파일에 다음의 내용을 적어서 src폴더에 저장하세요.
 
/** @page HowMakePages 새 페이지 예 새로운 페이지를 만들어서 MainPage에 추가하는 법을 알아봅니다. @section real 박스의 활용 @code 이 글은 Box안에 들어 갑니다. @endcode @section virtual 박스안의 인덴트 @code 이 글도 Box안에 들어 가겠죠? (단 앞에 인덴트가 있습니다.) 다음의 예와 같이 Box안의 글은 Doxygen문법이 적용되지 않습니다. 이런 이유로 code 자체를 보이기 위해 사용할 수 있습니다. @image html pooh.jpg - 항목 @endcode */
 
여기까지 했다면 command창에서 다음과 같이 실행하세요. 
 
C:\Work\hello_doxygen\src&gt;doxygen Doxyfile Warning: The selected output language "korean" has not been updated since release 1.4.6. As a result some sentences may appear in English. Searching for include files... Searching for example files... Searching for files in directory C:/Work/hello_doxygen/example Searching for images... Searching for files in directory C:/Work/hello_doxygen/res Searching for dot files... Searching for files to exclude Searching for files to process... Searching for files in directory C:/Work/hello_doxygen/src Reading and parsing tag files Preprocessing C:/Work/hello_doxygen/src/hello.cpp... Parsing file C:/Work/hello_doxygen/src/hello.cpp... 중간 생략 Generating file index... Generating example index... Generating file member index... Generating page index... C:\Work\hello_doxygen\src&gt;
 
정상적으로 되었다면 위와 유사한 메시지가 출력되면서 (경고 메시지도 있지만) 다시 프롬프트가 생겼을 겁니다.
 
이제 탐색기로 doc폴더에 가보면 html이라면 폴더가 생겨 있고 거기에 여러 파일들이 있는데... index.html 이라는 파일을 더블클릭해서 열어보면 다음과 같은 화면을 보실 수 있습니다.
 
3.png
 
html 파일들이 여기에 생기는 이유는 환경파일의 "OUTPUT_DIRECTORY"의 값으로 "../doc/"라고 줬기 때문입니다.
기왕 환경파일에 대한 이야기가 나왔으니 우리가 설정한 몇가지 값을 더 알아 보도록 하겠습니다.
"OUTPUT_LANGUAGE"는 문서화된 결과의 언어를 무엇으로 할지 결정합니다. 위의 화면 캡쳐에서 보면 "메인 페이지", "파일들", "관련된 페이지" 등은 우리가 어디에도 쓴 적인 없는데 알아서 한국어로 보여주고 있습니다. 이는 "OUTPUT_LANGUAGE"에 우리가 "Korean"이라고 지정해 주었기 때문이죠.
"INPUT_ENCODING" 값은 우리가 doxygen에게 처리해라고 할 파일들이 어떤 코드로 되어 있는지를 알려주는 것입니다. 여기에 쓸 수 있는 값은 iconv 프로그램이 처리하는 문자코드 이름을 적게 되는데 우리는 "EUC-KR", "CP949", "UTF-8" 등을 사용할 수 있습니다. 이중 우리는 윈도우에서 작업하고 있기 때문에 "CP949"라고 적었습니다.
"INPUT"은 처리해야할 파일들이 현재 doxygen을 실행하고 있는 곳을 기준으로 어디에 있는지를 알려주는 변수 입니다. 현재 src폴더에서 작업하고 있고 src폴더에 모든 작업파일들이 존재하므로 그냥 "."이라고 적었습니다. 
 
 
자 여기서 부터 설명하도록 하겠습니다.
이미 해버린 일이 상당히 많아서 설명할 것이 꽤 많을 것 같습니다.
 
우리가 지금 한 것은 MainPage를 만드는 것이 었습니다. 사실 이야기는 하지 않고 쭉 작업만 했지만 MainPage(mainpage.dox)와 일반페이지 하나(page.dox)를 더 만들었습니다.
 
Doxygen은 일반적인 소스파일 즉, *.c *.cpp *.h *.java 등의 파일과 확장자가 *.dox로 된 파일을 인식합니다. (파일이름은 중요하지 않습니다. 확장자가 중요합니다.)
 
그 중 "@mainpage"가 정의된 주석 블럭을 메인페이지를 구성하기 위한 내용으로 사용합니다.
 
여기서 "@mainpage"와 같은 것을 명령어라고 합니다.
 

<<여기서 한가지>>

명령어를 표시할 때
<>로 쓴 부분은  단일 단어를 사용해야 한다는 것을 의미합니다.
()로 쓴 부분은 그 라인의 끝까지 여러 단어를 사용 할 수 있다는 것을 의미합니다.
{}로 쓴 부분은 다음 문단까지 여러 단어, 여러 줄을 사용할 수 있다는 것을 의미합니다. (문단은 빈라인이 오거나 다음 section이 오면 끝납니다.)
[]로 쓴 부분은 생략 가능하다는 의미로 사용합니다. 
즉, "@section <section-name> [(section title)]" 에서 "@section" 다음에 "<section-name>"은 하나의 단어가 나타나야하고 "(section title)"은 여러 단어가 해당 줄에서 쓰일 수 있으나 생략도 가능하다는 의미입니다. 물론 @는 \로 사용할 수 있습니다.
  
1) @mainpage [(title)]
 
이 명령문이 적힌 주석 블럭을 메인페이지를 구성하기 위한 내용으로 사용합니다. MainPage의 제목은 환경파일의 "PROJECT_NAME"의 값이 사용되는데 이 @mainpage 명령어에 tilte을 적으면 이 title의 내용으로 MainPage의 제목이 변경됩니다. 단, MainPage의 제목을 의도적으로 적지 않으려면 "@mainpage notitle"이라고 하면 됩니다. 
 
@mainpage 헬로 프로젝트 헬로 프로젝트는 Doxygen을 테스트하기 위해 만드는 프로젝트입니다.
 
위와 같은 구문에 의해 다음과 같이 문서화 되었습니다.
 
4.png
 
 위의 화면에서 중간에 나타난 "1.0"이라는 숫자는 환경파일의 "PROJECT_NUMBER"의 값이 표시된 것입니다.
 
 
2) @section <section-name> [(section title)]
 
메인페이지를 구성하는 주요 명령어로는 "@section <section-name> [(section title)]" 이 있습니다.
이 "@section" 명령어는 일반 주석(소스의 주석) 블럭에는 나타날 수 없고 page 주석 블럭에만 사용할 수 있습니다. "@section"은 글을 쓰기 위한 큰제목을 생성한다고 보시면 됩니다. 여기서 <section-name>은 정해져 있지 않습니다. 그냥 여러분이 정하고 싶은 것을 영문으로만 작성하면 됩니다. 문서로 변환 될 때는 "section title"이 나타납니다. 만약 "section title"이 생략되면 "section-name"이 표시 됩니다.
 
각 섹션에는 일반적인 글을 적을 수도 있지만 "-"로 시작하는 항목을 적을 수 있습니다. "-"로 시작하는 글을 적으면 doxygen은 이를 "글머리기호"를 붙여서 항목을 나타냅니다. 또한 이들 항목은 인덴트(들여쓰기)를 할 수 있는데 <tab>으로 조절할 수 있습니다.
또한, 단순히 "글머리기호"가 아니라 "글머리번호"를 적고 싶다면 "-#"을 사용하면 됩니다.
이미 여러분이 작성한 mainpage.dox에서 마지막에 있는 "추가정보" Section의 내용을 실제로 문서화된 화면과 비교하여 보세요.
 
@section ADDINFO 추가정보 - 1레벨 인덴트 - 2레벨 인덴트(탭으로 들여쓸경우 하위 항목이 된다.) - 3레벨 인덴트(3레벨 이상은 글머리 기호는 바뀌지 않고 인덴트만 이루어 진다.) -# 번호매기기는 '-#' 방식으로 할수 있다. -# 2레벨 번호매기기 1 -# 2레벨 번호매기기 2 -# 3레벨 번호매기기 1 -# 3레벨 번호매기기 2 -# 4레벨 번호매기기 1 -# 4레벨 번호매기기 2 (4레벨 이상은 1레벨 번호와 같이 보여짐) -# 두번째 하위 항목
 
다음은 문서화된 실제 화면입니다. 
 
 5.png
 
 
3) @ref <name> ["(text)"]
 
참조할 페이지를 링크합니다. 이때 <name>은 page의 name을 의미합니다. (text)가 생략되면 링크를 할 문자로 <name>을 사용합니다.
 
@section Links 참고페이지 - @ref HowMakePages "새로운 페이지 만드는 방법"\n - @ref 야후: http://www.yahoo.co.kr
 
위와 같은 구문에 의해 다음과 같이 문서화 되었습니다.
 
 6.png
 
 
4) @image <format> <file> ["caption"] [<sizeindication>=<size>]
 
@image명령어는 문서에 그림파일을 연결하기 위해 사용합니다. <format>으로는 "html"과 "latex"를 사용할 수 있습니다. <file>은 파일 이름을 적으면 되는데 파일이름만 적었을 경우 환경파일의 "IMAGE_PATH"에서 찾게 됩니다. 우리는 이미 "IMAGE_PATH"에 "../res/"라고 적었습니다. "caption"은 이미지에 설명을 적는 부분이구요. <sizeindication>=<size>는 width, height 값을 적으면 되는데 <format>이 "latex"일 경우만 유효합니다.(예로 width=10cm 이런식으로 적습니다.)
 
@section Links 참고페이지 - @ref HowMakePages "새로운 페이지 만드는 방법"\n - @ref 야후: http://www.yahoo.co.kr
 
위와 같은 구문에 의해 다음과 같이 문서화 되었습니다.
 
7.png
 
 
여기까지 해서 MainPage를 작성했습니다. MainPage에 뭘 적어야 된다는 규칙은 없습니다.
다만 위와 비슷한 내용을 적게 되겠죠.
이번에는 새로운 페이지로 만든 page.dox 파일을 살펴보도록 하겠습니다.
 
5) @page <name> (title)
 
@page 명령어는 MainPage 외에 추가되는 페이지를 생성한다는 것을 의미합니다. @mainpage 명령어도 마찬가지 였지만 @page도 별도의 파일로 만들지 않고 소스파일에 포함시킬 수 있습니다. 하지만 소스가 지저분해지므로 별도 파일(page.dox)로 만든것이지요.
@page 명령어에서는 <name>이라는 것으로 다른 페이지에서 참조할 수 있습니다. 이미 우리는 MainPage에서 @ref 명령으로 이 값을 사용해 봤습니다. (title)은 페이지의 제목으로 사용하는 값입니다. <name>에는 영문자와 숫자를 사용할 수 있는데 대소문자를 구별하여 사용하고 싶다면 환경변수의 "CASE_SENSE_NAMES"의 값을 YES로 설정하세요. 단, 이 경우도 unix/linux와 같이 파일시스템 자체가 대소문자에 민감한 경우에만 허용됩니다. 호환성을 생각한다면 그냥 소문자로만 사용하세요.
 
@page HowMakePages 새 페이지 예 새로운 페이지를 만들어서 MainPage에 추가하는 법을 알아봅니다.
 
위와 같은 구문에 의해 다음과 같이 문서화 되었습니다.
 
8.png  
 
참고로 @page 명령에 의해 MainPage외에 추가된 페이지들은 상단의 "관련된 페이지"라는 탭에 모아지게 됩니다.
 
6) @code, @endcode 
 
@code와 @endcode는 한 쌍을 이뤄서 사용하게 됩니다. 주요 사용 용도는 HTML에 소스 코드 그대로를 보이고 싶을 경우 박스가 생기면서 글이 있는 그대로 적어지도록 하기 위해 사용합니다.
즉, @code와 @endcode 사이에 쓴 글은 html의 <XMP> 태그 처럼 doxygen 명령들의 확장없이 그대로 화면에 나타나 집니다. 화면 Box를 그려서 영역을 구분해 주므로 이와 같은 효과를 노리는 경우에도 사용합니다.
 
@code 이 글도 Box안에 들어 가겠죠? (단 앞에 인덴트가 있습니다.) 다음의 예와 같이 Box안의 글은 Doxygen문법이 적용되지 않습니다. 이런 이유로 code 자체를 보이기 위해 사용할 수 있습니다. @image html pooh.jpg - 항목 @endcode
 
위와 같은 구문에 의해 다음과 같이 문서화 되었습니다.
 
9.png  
 
자 우선 여기까지 해서 메인페이지와 추가적인 페이지를 만들어 보았습니다.
 
다음 강좌에는 실제 소스 코드에 주석을 달아 문서화 해 보도록 하겠습니다. 
   
 
 
Creative Commons License
Creative Commons License이 저작물은 크리에이티브 커먼즈 코리아 저작자표시-비영리-동일조건변경허락 2.0 대한민국 라이센스에 따라 이용하실 수 있습니다.
Copyright 조희창(Nicholas Jo). Some rights reserved. http://bbs.nicklib.com