Borland C++ Builder 6: Doxygen으로 Source Code 문서화하기 (Part 1)

Doxygen은 여러 Programming Language를 위한 문서화 도구입니다. Source Code를 문서화한다는 것은 Code내의 주석을 통하여 Code의 구조와 Interface를 문서로 만드는 것을 의미합니다.

Doxygen을 사용하면 C++, C, C#, Fortran, Java, Objective-C, PHP, Python 등의 언어를 사용한 Source Code에 Doxygen에서 정의한 Style로 주석을 작성하면 자동으로 문서를 생성할 수 있게 됩니다.

생성된 문서는 마치 MSDN이나 기타 Live API Document와 같은 형식으로 Web Browser, PDF Reader, CHM Help 등으로 열람이 가능합니다. 이것은 여럿이 동시에 작업하는 Project에 더욱 유용합니다.

이번 Post에서는 Borland C++ Builder 6로 작성한 Project를 Doxygen을 사용하여 문서화하는 방법을 다루도록 하겠습니다.

Contents [hide]

• 1. Doxygen 설치
• 2. Source Code에 문서화를 위한 Comment 작성
  • 2.1 Class comment template
  • 2.2 Method comment template
  • 2.3 Mainpage comment template
• 3. 마치면서…

1. Doxygen 설치

Doxygen 자체는 Source Code의 주석을 사용하여 문서를 자동으로 생성하는 도구로서 IDE와 통합되어 동작하지 않습니다. 다만 Doxygen에서 정의한 Style에 주석을 Project 개발시에 Source Code에 작성하면 됩니다. (Java, Flex의 경우에는 문서화 도구인 JavaDoc, ASDoc Style로 작성한 주석을 바로 Parsing하여 Eclipse에서 해당 Class나 Method에 대한 주석을 바로 확인할 수 있습니다.)

또한 Doxygen은 Cross-Platform Tool로서 Windows, Mac OS X, Linux (or Unix-like OS)에서 사용이 가능합니다. 이것은 Windows Application의 Source Code를 Doxygen에서 지정한 형식으로 주석을 작성해 놓으면, Web Server가 동작하는 다른 OS에서 Doxygen을 사용하여 Source Code 문서를 생성할 수 있다는 것을 말합니다. 한마디로 해당 Project에 대한 API Web Service(like MSDN)를 운영할 수 있게 됩니다.

이제 어느정도 설명이 끝났으니 설치를 해보도록 합시다. Doxygen의 Homepage에 접속합니다.

Doxygen Site

Program을 Download하기 위해서 오른쪽의 Download를 Click합니다.

Doxygen Download

여러 OS에 대한 Binary가 존재하는데 여기에서는 32-bit binary distribution for Windows XP/Vista/7 Section의 설치 File을 Download합니다.

Doxygen Install

Download한 설치 File을 설치합니다. 설치 중간에 위와 같이 Doxygen 구성요소가 나오는데 여기에서 Doxywizard GUI를 선택합니다.

Doxywizard를 사용하면 Command-line 기반의 Doxygen을 좀 더 편리하게 쓸 수 있습니다.

Graphviz Site

그리고 한 가지 더 설치해야 할 Tool이 있습니다. Doxygen은 문서를 생성할 때 Class나 Method의 관계를 나타내기 위해서 Graphviz라는 Tool을 사용합니다. 이번에는 Graphviz를 설치하도록 합시다.

Graphviz의 Homepage에서 왼쪽 Download를 Click합니다.

Graphiviz License Agreement

License 동의를 위해서 맨 아래쪽의 Agree를 Click합니다.

Graphviz Download

Windows – Stable and Development Windows Install Packages를 Click하여 Download한 후 설치하면 모든 준비는 완료됩니다.

2. Source Code에 문서화를 위한 Comment 작성

BCB6 - Doxygen Test Project

설치가 모두 끝났으니 이제 Source Code에 Doxygen Style의 주석을 달아봅시다. Style 및 사용하는 Metatag는 여러가지가 있는데 여기서는 간단하게 주로 사용하는 것을 Template 형태로 적어보도록 하겠습니다.

좀 더 자세한 내용을 알기 원한다면 아래의 Doxygen Manual을 참조하기 바랍니다.

• Online Manual : http://www.stack.nl/~dimitri/doxygen/download.html#latestman
• 설치된 Manual : C:\Program Files\doxygen\html\index.html
  (64bit OS일 경우에는 C:\Program Files (x86)\doxygen\html\index.html)

2.1 Class comment template

Class에 대한 주석을 작성할 때는 아래와 같이 작성하면 됩니다. 아래의 예제에서는 Class에 대한 주석 뿐만 아니라, 전역 변수, Method에 대한 주석도 설명하고 있습니다.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25

/**  * 짧은 Class 설명  *  * @author  ioriy2k <ioriy2k@ioriy2k.pe.kr>  *  * 긴 Class 설명을 여기에 적습니다.  */ class Test { private:     /// 전역변수에 대한 한 줄 설명     bool test_flag;     /**      * 전역변수에 대한 긴 설명을 작성할 수 있습니다.      * 여러 줄로 표현이 가능합니다.      */     bool test_flag1; public:     /// Method에 대한 한 줄 설명         Test(); };

위와 같은 주석을 작성한 후, Doxygen으로 문서를 생성한 모습은 다음과 같습니다.

HTML - Class Description

2.2 Method comment template

Class의 Metho에 대한 주석을 작성할 때는 다음과 같이 작성하면 됩니다.

1 2 3 4 5 6 7 8 9 10 11

/**  * 짧은 Method 주석  *  * 긴 Method 주석을 여기에 작성합니다.  *  * @param    run    Parameter명을 먼저 적고 그 이후에 변수에 대한 정보를 적습니다.  * @return return 값이 존재하는 경우 Return 값에 대한 정보를 적습니다.  */ bool Test::RunTest(int run) { }

Parameter가 여러 개일 경우에는 Parameter의 순서대로 @param을 사용하여 설명을 적습니다. 개인적으로는 Debugging을 하기 위해서 header를 반복해서 살펴야 하는 Case를 가능하면 피하기 위해서 Method 주석은 header보다는 cpp에 적는 편입니다.

위와 같이 작성한 주석을 가지고 Doxygen으로 문서를 생성한 모습은 다음과 같습니다.

HTML - Method Description

2.3 Mainpage comment template

Mainpage는 Doxygen 문서의 Mainpage(index.html)를 주석으로 생성하는 것을 의미합니다. Mainpage 주석은 Source에 오직 한 군데만 작성해야 하며 이 곳은 주로 Project의 개관, 알아두어야 할 정보나 Compile 방법 등을 적어 놓는데 사용합니다.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19

/**  * @mainpage Project 제목  *  * @section overview Overview  *  * Section에 대한 설명을 여기에 적습니다.  *  * @section list List  *  * 다음과 같이 순서가 없는 List를 작성할 수 있습니다.  *  * - List 1  * - List 2  *  * 다음과 같이 순서가 있는 List를 작성할 수 있습니다.  *  * -# List 1  * -# List 2  */

위와 같은 Mainpage Comment를 Doxygen으로 문서화하면 다음과 같은 모습이 됩니다.

HTML - Mainpage

3. 마치면서…

이상으로 Doxygen을 설치하는 방법과 문서 생성을 위해 Source Code에 주석을 다는 방법을 알아봤습니다. 다음 Post에서는 Source Code에 작성한 주석을 Doxywizard를 사용해서 HTML과 CHM 문서로 만드는 방법을 알아보도록 하겠습니다.