Doxygen을 사용하여 소스코드를 문서화 하자!

invalid-file

invalid-file

invalid-file

invalid-file

프로그래머라면 문서화 작업에 대해서 상당히 신경이 쓰이는것이 사실이다.
복잡한 코드 및  설정 환경들을 하나하나 설명해야 한다는것은 여간 까다로운 것이 아니다.

오늘 발견한 Tool은 소스코드를 하나의 보기 좋게(?) 정리할 수 있는 Doxygen이다.

사실 아직 많은것을 사용하지 않아서 뭐가 뭔지는 잘 모르겠지만...
간략히 사용법을 적어본다.

1. 설치
   doxygen 홈페이지 http://www.stack.nl/%7Edimitri/doxygen/index.html
   위 사이트에서 doxygen을 다운 받는다. 현재 버젼은 doxygen-1.5.6이다.
   윈도우 버젼인 doxygen-1.5.6-setup.exe를 다운 받거나,
   첨부한 doxygen-1.5.0-setup.exe를 받아서 실행하면 된다.
   개인적으로 doxygen-1.5.0-setup.exe을 사용하길 바란다.
   doxygen-1.5.6-setup.exe은 한글이 깨지는듯 싶었다. 아니면 내가 설정을 잘 못했던가..??
   각설하고 설치를 해보자.

    -  Next를 눌러야겠지?

    -   동의를 해야겠지?

    - 설치 경로를 선택하고 Next

     - 그냥 Next

     -  Next

    -  Install

     - Next

     - 설치가 끝났다.

         
             
2. 추가 설치
    - 그래프를 표현하기 위한 추가 프로그램 : http://www.graphviz.org/Download_windows.php
       graphviz-2.20.2.exe을 다운받아 설치한다.
    - htmlhelp.exe, KingsSetup.msi는 원하는대로 설치한다.


3. 이제 doxygen을 실행해 보자.
   실행에 앞서 예제 소스코드가 필요하다.

// doxygen.cpp : 콘솔 응용 프로그램에 대한 진입점을 정의합니다.
//
/** \mainpage doxygen
\section developer 개발자
- Erato
\section info 개발목적
- doxygen 테스트

\section advenced 추가정보
- 사용 환경
 - x86계열
  -# WinXP 권장
 
 - Linker
  -# WinSock2 : Ws2_32.lib
  -# Network Info : Iphlpapi.lib
\image html option.jpg
*/

#include "stdafx.h"
#include <iostream>
using namespace std;
//! @brief doxygen 클래스
//!
//! 클래스 테스트를 한다.
class doxygen
{
public:
 doxygen(); //!< 생성자
 ~doxygen(); //!< 소멸자
public:
 void ShowDoxygen(char* psz);   //!< ShowDoxygen
 int  GetDoxygenPath(char* psz);  //!< GetDoxygenPath
};

/** \brief
 생성자
\remarks
 doxygen() 생성자
\return
 없음.
*/
doxygen::doxygen()
{
 // 아무런 의미 없다.
}
/** \brief

/** \brief
 소멸자
\remarks
 doxygen() 소멸자
\return
 없음.
*/
doxygen::~doxygen()
{
 // 아무런 의미 없다.
}

/** \brief
 내용을 출력한다.
\remarks
 char*로 넘겨온 내용을 출력한다.
\return
 없음.
*/
void doxygen::ShowDoxygen(char* psz) //!< 출력할 내용      
{
 if ( psz != NULL )
 {
  cout << psz << endl;
 }
}

/** \brief
 내용을 입력한다.
\remarks
 char*로 넘겨온 내용을 입력한다.
\return
 성공시 0을 반환하고, 실패시 -1을 반환한다.
*/
int doxygen::GetDoxygenPath(char* psz) //!< 입력할 내용
{
 int retval = -1;
if ( psz != NULL )
 {
  // 아무런 의미 없다.
  retval = 0;
 }

/** \brief
 main함수
\remarks
 실행할 main함수다.
\return
 성공시 0을 반환하고, 실패시 -1을 반환한다.
*/
int _tmain(int argc, _TCHAR* argv[])
{
 doxygen _dox;
 _dox.ShowDoxygen("Hello doxygen!");
if ( _dox.GetDoxygenPath("test") == 0 )
 {
  return -1;
 }
return 0;
}

 3.1 Doxygen wizard 실행

- doxygen wizard를 실행 시킨다.

 

  3.2 wizard 설정

- wizard 버튼을 클릭한 후 다음을 설정을 한다.

Project Tab

       - project name 및 버젼 등의 내용을 적고, source code가 존재하는 디렉토리를 설정한다.
          Scan recursively를 선택할 경우 해당 디렉토리의 하위 디렉토리를 모두 포함한다.
          마지막으로 출력 디렉토리를 설정한다.


Mode Tab

        - C++로 설정
        - 만약에 make file project라면 원하는 h/hpp/c/cpp 파일들만 한곳에 모아놓고
         그곳 폴더만 지정한다. 그리고 위의 항목중에 'Include cross-referenced source code int the output'을 선택해준다. 그러면 해당하는 폴더에서 클래스 구조등과 같은것들을 만들어준다.



Out Tab

        - HTML로 설정한다.


Diagrams Tab

        - GraphViz를 설치했으므로 선택한다.

   
  3.3 Export 설정

Project Tab에서 언어를 선택한다. 다른 탭에서의 설정은 좀 더 알아보고 설정해도 상관 없을 듯 싶다

 
4. Save

- Save 버튼을 클릭하여 지금까지 설정한 doxygen 환경 파일을 저장한다.

5. 작업 디렉토리를 설정한다.

- 로그 파일등을 지정할 디렉토리를 선택한다. 위와 동일한 디렉토리를 사용했다.

6. Start

- Start 버튼이 활성화 되었다. 클릭해서 문서를 만들어 보자.

- warning 메세지가 발견되었다. option.jpg 파일이 없다는거네?
  option.jpg 파일을 내가 만든 이미지 파일이다. 무시하고 나중에 같은 이름의 이미지 파일을
  생성한 폴더에 넣어주면 해결된다.

7. 문서를 확인해보자.

- 이미지 파일을 폴더에 넣어주었고, 문서를 확인하려면 index.html 파일을 더블 클릭한다.

이렇게 해서 doxygen을 이용한 소스코드를 문서화해봤다.
여기서는 소스코드가 간단해서 엉성해 보이지만, 여러개의 클래스가 상속받고,
코드가 복잡해지면 제법 문서다워진다(?)

여하건 프로그래머에게 있어서 주석만 제대로 달아도 상당히 유용한 문서 관리가 될 것이다.
적극 활용하자. 코딩하고 나서 나중에 알아보기 힘들어지기 전에 말이다.

참고>
1.http://blog.tinywolf.com/entry/Doxygen%EC%9D%84-%EC%82%AC%EC%9A%A9%ED%95%9C-%EC%BD%94%EB%93%9C-%EB%AC%B8%EC%84%9C-%EC%89%BD%EA%B2%8C-%EC%83%9D%EC%84%B1%ED%95%98%EA%B8%B0
2. http://studycan.tistory.com/archive/20080606