메뉴 건너뛰기


Developer > Development Tools

Doxygen 4장. Doxygen 응용 2/3

2013.11.16 01:36

푸우 조회 수:8505

이번에는 저번 강좌에서 생성했던 프로젝트를 대상으로 실제 코드 문서화를 해 보도록 하겠습니다.
 
 
4장. Doxygen 응용 2/3
 
이미 문서화된 결과를 보셨죠? 나름 깔끔합니다.
하지만 보는 사람에 따라서는 안 예쁠 수도 있죠.
그래서 이번에는 문서화된 결과의 전체적인 디자인을 좀 바꿔 보겠습니다.
 
1. Header와 Footer 설정
 
Doxygen에서 만들어낸 문서는 내용 만을 HTML로 저장하고 디자인과 관련된 부분은 StyleSheet에 저장하고 있습니다. 그러므로 StyleSheet를 변경하면 전체적인 색감이나 기타 등등을 변화 시킬 수 있습니다.
 
또한 전체 윤곽에 크게 영향을 미치는 상단부분(Header)과 하단부분(Footer)을 별도의 파일로 만들어 각 문서 생성시 사용할 수 있도록 되어 있습니다.
 
이와 관련된 환경변수가 "HTML_HEADER"와 "HTML_FOOTER" 입니다.
지금 src폴더에 있는 Doxyfile을 열어서 위의 항목을 찾아 다음과 같이 수정하세요.
 
HTML_HEADER            = header.html
HTML_FOOTER            = footer.html
 
그리고 src폴더에 header.html 파일과 footer.html 파일을 생성하고 각각 다음과 같이 생성하십시오.
먼저 header.html 파일입니다.
<HTML>
  <HEAD>
    <TITLE>$title</TITLE>
    <LINK HREF="doxygen.css" REL="stylesheet" TYPE="text/css">
  <LINK HREF="tabs.css" REL="stylesheet" TYPE="text/css">
  </HEAD>
  <BODY BGCOLOR="#FFFFFF">
 
다음은 footer.html파일입니다. 
<hr size="1">
<address style="text-align: right;"><small>$projectname 문서화. 생성일시 : $datetime &nbsp;
<a href="http://www.doxygen.org/index.html">
<img src="doxygen.png" alt="doxygen" align="middle" border="0">
</a> $doxygenversion
</small>
</address>
 </BODY>
</HTML>
 
header.html과 footer.html 파일을 생성한 후 doxygen을 돌려 html 문서를 새로 만들면 "여기는 Header 부부입니다."와 "여기는 Footer부분입니다."라는 메시지를 출력하고 것 만 빼고 전과 똑 같은 화면을 보실 수 있습니다. 어찌되었건 이제부터 header.html과 footer.html를 변경하고 문서를 만들면 이것 들이 반영된다는 것이죠.
그런데 자세히 보시면 $title 과 같이 특정 변수 형태로 사용된 값들이 있습니다.
이렇게 header와 footer에 사용할 수 있는 변수로는 다음과 같은 것들이 있습니다.
 
  • $title : 문서의 제목을 출력하게 됩니다. 일반적으로 <title>태그에 사용하게 됩니다.
  • $datetime : 문서화를 시킨 날짜와 시간을 출력합니다.
  • $date : 문서화를 시킨 날짜를 출력합니다.
  • $doxygenversion : 문서화를 시킨 doxygen의 version정보를 출력합니다.
  • $projectname : 프로젝트의 이름을 출력합니다. 이 값은 환경변수 "PROJECT_NAME"에 설정된 값입니다.
  • $projectnumber : 프로젝트의 번호를 출력합니다. 이 값은 환경변수 "PROJECT_NUMBER"에 설정된 값입니다.
 
자 여기까지 했으면 실제로 소스에 주석을 달아보도록 하겠습니다.
 
2. 그래프와 소스파일 주석
 
소스에 주석을 달기 전에 현재 소스를 어떻게 문서화 하고 있는지 우선 살펴보겠습니다.
 
1) DOT 툴을 이용한 그래프
 
상단의 탭중에 "파일들"이라는 부분을 클릭하면 다음과 같은 화면을 볼 수 있습니다.
 
1.png
 
여기서 파일 목록을 보여주고 해당 파일의 문서화 페이지와 해당 파일의 코드를 볼 수 있도록 링크가 되어 있습니다. 여기서 코드를 볼 수 있는 이유는 환경변수중 "SOURCE_BROWSER"의 값을 YES로 했기 때문입니다. 현재는 코드를 봐도 별건 없고 그냥 소스 그대로가 보입니다.
"hello.cpp"를 클릭하면 문서화된 모습을 볼 수 있는데... 다음과 같습니다.
 
2.png
 
3.png
 
위와 같이 근사한(?) 그래프도 보여 주는 문서가 작성되어 있음을 알 수 있습니다. 그래프를 제외하고는 아직 함수의 원형 정도를 보여주는게 전부지만 그래도 뭔가 좋아 보이지 않나요? (ㅋㅋ)
이것이 바로 DOT언어를 이용하여 그래프를 그리는 Graphviz - Graph Visualiation Software 툴을 사용한 결과입니다. Doxygen은 소스파일의 포함관계나 함수의 호출 관계를 파악하여 각각 DOT 언어 파일을 생성합니다. 그런 다음 Graphviz라는 툴을 돌려 이미지를 만들고 이를 링크합니다.
이것이 가능하도록 하기 위해 환경 변수에 "HAVE_DOT"을 YES로 지정했었습니다. 물론 이것은 DOT 툴을 가지고 있으니 DOT 언어 스크립트 파일을 생성하라고 Doxygen에게 알려주는 역할을 하죠.
DOT툴은 "DOT_PATH" 환경변수에 실제 툴이 있는 경로를 적어 주었습니다. 문서화된 결과 중 제일 위의 그림은 "INCLUDE_GRAPH" 환경변수가 YES로 되어 있어서 출력된 결과입니다. 현재 소스에는 클래스가 하나 밖에 존재하고 있지 않아서 표시는 되지 않았지만 서로 상속관계를 갖는 클래스 들이 있다면 "CLASS_GRAPH" 환경변수에 의해 표시가 됩니다.
문서의 각 함수 설명에 표시되는 그래프는 해당 함수를 누가 호출하는지를 혹은 어떤 함수를 호출하는지에 대한 관계도를 표시하고 있는데 이는 환경변수 "CALL_GRAPH"와 "CALLER_GRAPH"를 YES로 지정하였기에 나타나는 결과입니다.
단순 그림으로만 존재하는 것은 아니고 해당 함수나 파일로 링크를 할 수 있다면 그래프중 노드를 클릭하여 이동 할 수도 있습니다. 위의 경우 함수 호출 관계도에서 하얀 상자를 클릭하면 이동이 가능하네요.
 
또 제일 상단의 탭을 다시 "파일들"을 선택하고 "파일멤버"를 클릭하게 되면 다음과 같이 함수 리스트를 보여 주게 됩니다.
 
4.png
 
 
 
2) @file [<name>]
 
 @file 명령어는 하나의 파일에 한번 다는 주석입니다. 즉 문서화 대상 파일 자체를 설명하기 위한 명령어죠. <name>에는 설명하고자 하는 파일의 파일명을 적습니다. @file 명령어가 설명하는 파일에 @file주석이 있어야 되는 것은 아니구요. 어디에 있든 <name>에 적은 파일을 설명하면 됩니다. 하지만 일반적으로는 해당 파일의 제일 앞에 적는 것이 일반적이죠. 해당 파일에 직접 적을 경우는 <name>을 생략할 수 있습니다.
 
hello.cpp파일에 다음과 같은 구문을 파일의 제일 앞에 넣어 보세요.
/** * @file hello.cpp * main함수 부분와 Hello 클래스 구현. * * 프로그램의 main함수와 Hello클래스를 구현하는 파일입니다. * * @author 조희창 (nicholas@naver.com) * @date 2007/10/23 * @attention Copyright (c) 2007 NICKLIB - All rights reserved. *****************************************************************************/
 
그리고 hello.h파일에 다음과 같은 구문을 파일의 제일 앞에 넣어 보세요. 
/** * @file hello.h * Hello 클래스 선언. * * Hello클래스를 선언 한 파일입니다. * * @author 조희창 (nicholas@naver.com) * @date 2007/10/23 * @attention Copyright (c) 2007 NICKLIB - All rights reserved. *****************************************************************************/
 
이름이나 Email 등을 적당히 바꾸셔도 상관없습니다.
 
저장하셨으면 다시 doxygen을 돌려 문서를 만들어 보세요.
 
그리고 문서의 상단 탭에 "파일들"을 클릭해서 "파일 목록"을 보세요.
다음과 같이 되어 있음을 확인 할 수 있을 것 입니다.
5.png
 
hello.cpp에 적은 @file 명령어에 의해 해당 파일을 설명하는 내용이 추가 되었네요. 이미 설명한 바와 같이 간단한 설명 부분만이 우선 목록에는 나타나 있습니다. 여기서 한가지 원래 간단한 설명은 @brief 명령어를 사용하게 되는데 환경설정에서 "JAVADOC_AUTOBRIEF"를 YES로 설정했기 때문에 @brief를 사용하지 않아도 간단한 설명으로 인식됩니다.
 
그런데 한가지 의아(?)한 것은 hello.cpp는 목록에 나타났는데 hello.h 파일은 나타나지 않았군요.
hello.h는 다른 디렉토리에 있기 때문에 그렇습니다. hello.h를 포함 시키는 방법은 두가지가 있는데...
환경변수 중 "INPUT"에 "./include/"를 추가하든지 아니면 "RECURSIVE" 변수의 값을 YES로 바꿔 주면 됩니다. 여기서는 "RECURSIVE"의 값을 YES로 바꾸도록 하지요. 값을 바꾼 후 다시 doxygen을 실행하면 이제 hello.h 파일도 다음과 같이 문서에 포함되게 됩니다.
 
6.png  
 
자세히 보면 헤더 파일 하나 추가되었을 뿐인데... 많은 부분이 바뀌었음을 알 수 있습니다.
 
helo.h에 대한 문서가 추가되었음은 물론이고  상단의 탭 부분에 "데이터 구조"라는 탭이 생겼습니다.
게다가 좀전에 봤던 hello.cpp의 문서에서 그래프도 다음과 같이 더 복잡(?)하게 바뀌었군요.
 
7.png   
 
이것 저것 한번 살펴보시구요.
 
실제로 @file 명령어에 의해 변한 내용을 살펴보도록 하겠습니다.
 
hello.cpp 파일과 hello.h파일의 문서 중 처음에 간단한 설명이 추가 되었구요. 조금 밑에 "세부 사항" 부분에 작성한 주석이 적혀 있음을 알 수 있습니다.
8.png
 
@file 명령어 블록 안에 여러 명령어들이 사용되었는데...
명령어에 대한 설명은 하지 않고 그냥 원형표기에 의한 나열만 하겠습니다.
뭐 직관적인 명령어 들이라 굳이 설명이 필요없을 듯...
 
@author { list of authors }
@date { date description }
@attention { attention text }
 
 
2. 함수에 주석 달기
 
 
이제 각 함수에 문서화를 위한 주석을 달아 보도록 하겠습니다. hello.cpp 파일의 Usage()함수 바로 위에 다음과 같은 내용을 적습니다. 
/** * 사용법을 출력합니다. * * Hello프로그램의 사용법을 출력합니다.\n * 실제 출력 내용은 다음과 같습니다.\n * @code * Usage: hello &lt;yourname&gt; * @endcode * * @see main */ void Usage(void)
 
main()함수 위에는 다음과 같은 주석을 달아 보세요.
 
/** * 메인함수입니다. * * 사용자로 부터 이름을 입력 받아 Hello &amp;lt;yourname&amp;gt;이라는 문자열을 출력합니다. * * @param[in] argc 아큐먼트의 갯수가 입력됨 * @param[in] argv 아큐먼트의 실제 내용이 입력됩니다. * @return 성공시 0, 오류시 -1을 리턴 * @remarks 여기는 주석에 주석입니다. * @par 요구사항 * string.h 가 필요함 (별도의 항목은 이렇게 만듦) * @par 점검사항 * 입력이 정상적인가에 대한 점검이 필요함 * @exception NULL_EXCEPTION NULL문자가 들어오면 Exception 발생 * @see Usage */ int main(int argc, char *argv[])
 
 이런 다음 doxygen을 실행시키고 문서를 보시면 다음과 같은 내용이 바뀌었음을 알 수 있습니다.
9.png
 
10.png
 
11.png
 
이제 각각의 명령어에 대해 알아보도록 하지요. 
 
1) @see { references } / @sa { references }
 
@see 명령어는 @sa와 같습니다. 원래 @sa인데 JavaDoc의 호환을 위해 @see명령어를 제공하는 것입니다.  {references}에 사용할 수 있는 값으로는 클래스, 함수, 메소드, 변수, 파일의 이름과 URL입니다. 만약 클래스내의 어떤 멤버변수를 참조로 링크하고자 한다면 ::나 #를 사용하여 클래스와 변수이름을 연결하여 사용하면 됩니다.
 

<<참고>>

주석으로 사용한 문장들은 HTML로 보여지게 되는데 문장 자체에 HTML 태그를 사용하여 문장을 장식할 수도 있습니다. 또한, 주석에서 줄바꿈을 했다고 해서 자동으로 HTML 문서에서도 줄바꿈이 되지는 않습니다. 줄바꿈을 시킬려면 <br>태그나 \n 을 사용하여 줄바꿈을 할 수 있습니다.
 
 
2) @param <parameter-name> { parameter description }
 
@param명령어는 함수에 사용되는 매개변수를 설명하기 위한 명령으로 사용됩니다. <parameter-name>은 실제 매개변수의 이름을 쓰면 되구요. 그 뒤에 해당 매개변수를 설명하는 글을 쓰면 됩니다.
특별하게 @param 다음에 [in] 혹은 [out]을 사용할 수 있는데 이는 함수 입장에서 입력 매개변수 인지 아니면 출력 매개변수인지를 명시하기 위해 사용합니다.
 
3) @return { description of the return value } / @retval <return value> { description }
 
@return 명령어는 함수가 리턴하는 값에 대한 설명을 달기 위해 사용합니다. 단순하죠? 그래서 한가지 더 이야기 하면 이렇게 return 값에 대한 설명을 줄줄이 달수도 있지만 @retval 명령어를 사용하여 각 리턴값을 설명할 수도 있습니다. @retval은 "@retval <return value> { description }"과 같이 사용할 수 있구요. 예를 들어 보면 다음과 같습니다.
 
@retval  0  성공
@retval -1 실패
 
위와 같이 사용하면 문서에 다음과 같은 결과가 나타납니다.
12.png
 
 
4) @remarks { remark text }
 
단순하게 설명을 쓰는 명령어 입니다. 더 할말이 쩝~ 없음
 

5) @par [(paragraph title)] { paragraph }
 
사용자가 항목을 정의해서 설명을 다는 명령어입니다. (paragraph title)은 항목명, {paragraph}는 설명을 쓰면 되는데 (paragraph title)을 생략하면 들여쓰기 한 것과 같은 효과를 볼 수 있습니다.
위의 예는 단독으로 사용했는데... @param, @warning 과 같은 다른 명령어의 내용에 들여쓰기 효과를 위해 사용할 수 도 있습니다. 
 
6) @exception <exception-object> { exception description }
 
함수의 예외 처리에 대해서 설명합니다. <exception-object>는 예외객체를 쓰면 되구요. {exception description}은 예외의 설명을 적으면 됩니다.
 
7) 함수내에 문서화 주석 사용하기
 
함수에 대한 설명을 함수 주석에 모든 적을 필요는 없습니다.
함수 내에 주석을 달더라도 와 같이 doxygen이 인식하는 형식을 사용하면 이 내용이 함수의 상세 설명으로 들어가게 됩니다. main()함수를 다음과 같이 바꿔보세요.
 
int main(int argc, char *argv[]) { if(argc&lt;2) { Usage(); return -1; } /** main함수에서는 Hello 클래스를 사용합니다.\n 입력받은 첫번째 아큐먼트를 Hello 클래스 인자로 넘깁니다. */ Hello *hObj=new Hello(argv[1]); /// 입력받은 아큐먼트를 Hello객체에 담았다가 stdout으로 출력합니다. cout &lt;&lt; hObj-&gt;getUserName() &lt;&lt; "\n"; delete hObj; return 0; }
  
 그런 다음 doxygen을 돌리고 html문서를 보세요. 그러면 위에 쓴 주석이 다음과 같이 추가 되었음을 알 수 있습니다.
13.png
 
 그런데... 주석의 내용 중 "" 부분은 문서내에 존재하지 않죠? 이것은 일반 주석 형식으로 사용했기 때문에 문서화는 되지 않습니다. 단, 이 부분은 소스브라우징(즉, 코드보기)에서 실제 소스 코드 내에 표시되게 됩니다.
 
14.png
 
그런데 소스 코드 보기에서는 문서화 주석은 또 보이질 않네요. 만약 문서화 코드도 보고 싶으시다면 환경 변수 중 "STRIP_CODE_COMMENTS"를 NO로 설정하세요. 그럼 다음과 같이 문서화 주석들도 코드 내에서도 볼 수 있습니다. (취향에 맞게 활용하세요.)
15.png
 
 
이번 장에서는 주로 함수에 관련된 주석다는 법을 알아 봤는데... 다음 장에서는 클래스에 주석 다는 법을 알아 보도록 하겠습니다.
 
 
Creative Commons License
Creative Commons License이 저작물은 크리에이티브 커먼즈 코리아 저작자표시-비영리-동일조건변경허락 2.0 대한민국 라이센스에 따라 이용하실 수 있습니다.
Copyright 조희창(Nicholas Jo). Some rights reserved. http://bbs.nicklib.com