Doxygen을 사용한 코드 문서 쉽게 생성하기

공동 혹은 협력 개발 작업을 하다가 보면 서로의 정보를 공유하기 위해
매우 다양한 방법을 사용하게 됩니다.

그러한 방법 중에 하나로 서로가 개발한 부분의 사용법이나
자세한 작동 내용을 설명하기 위해 클래스나 함수들의 용법을 설명하는
문서를 자주 사용하게 됩니다.

그런데 이러한 문서를 작성하고 있다보면
개발보다 결코 쉽지 않고 만만치 않은 시간이 소비됩니다.
이미 개발하는 당사자도 많은 주석을 통해 코드 곳곳에 정보를 남겼을 것인데
이를 다시 보기 좋게 정리하고 문서에 투자하는 시간은 어쩌면 낭비되는 시간일지도 모릅니다.

이러한 고민이 아주 오래전부터 있었던 모양입니다.
벌써 많은 문서화 툴이 제작되고 사용되고 있는 중이지요.

이 글에서는 그중에 비교적 빨리 적응할 수 있고
오픈 소스 정신에 입각하여 누구나 사용할 수 있는 Doxygen을 소개하고자 합니다.

역시나 많은 분들이 사용하는 Windows XP 이상을 기반으로 설명할 것이며
DoxyWizard를 사용하는 것을 주로 설명합니다.

1. 설치
    관련 주소 : http://www.stack.nl/~dimitri/doxygen/ - 개발자의 홈페이지
 우선 다운로드 주소에서 윈도우즈용 최신 버전을 다운로드해서 설치합니다.
 그리고 그래프를 표현하기 위한 프로그램인 Graphviz도 다운로드해서 설치합니다.

2. 테스트용 소스
 다음과 같이 테스트용 소스를 만들었습니다.
 Doxygen은 다양한 형식의 주석을 지원합니다만 아래의 테스트 코드는 제가 흔히 사용하는 스타일로 적어 보았습니다. Doxygen의 문법은 KLDPWiki를 참고하시면 좋습니다.

소스 보기

디렉토리 구조

E:\Work\Doxygen_example

├ src

│ ├ main.cpp

│ └ class.cpp

└ inc

└ class.h

--- main.cpp의 코드 ---

#include "class.h"

//! 메인 함수

int main(void)

{

    // 메세지 출력

    printf(_T("Hello! Doxygen\n"));

    // 질문 메세지 박스 출력

    cDoxyClass test;

    bool ans = test.showQuestionBox(_T("Doxygen 마음에 드십니까?"), _T("질문"));

    // 반응 출력

    if (ans)

        printf(_T("아이고 감사합니다.\n"));

    else

        printf(_T("이런 죄송합니다.\n"));

    // 정상 종료

    return 0;

}

--- class.h의 코드 ---

//! @brief Doxygen 예제용 클래스

//!

//! Doxygen 주석 문법을 설명하기 위한 간단한 예제용 클래스입니다.\n

//! 뭐 특별히 하는 일은 없습니다.

lass cDoxyClass

{

protected:

    int m_nNum;    //!< 메세지 박스 출력 횟수

public:

    //! 생성자

    cDoxyClass();

    //! 소멸자

    virtual ~cDoxyClass();

public:

    //! @brief 질문 메세지 박스 출력

    //!

    //! 최상위에 Yes/No로 질문하는 메세지 박스를 출력합니다.

    //! @return Yes를 선택하면 true, 그 외에는 false

    bool showQuestionBox(

         const TCHAR* msg            //!< 질문 내용

        , const TCHAR* title = NULL    //!< 메세지 박스 제목

        );

    //! 메세지 박스 출력 횟수 얻기

    //! @return 메세지 박스 출력 횟수

    int getNum(void);

};

//! @brief Doxygen 예제용 하위 클래스 1

class cDoxySubClass1 : public cDoxyClass

{

public:

    int getNum(void) { return 1; }

};

//! @brief Doxygen 예제용 하위 클래스 2

class cDoxySubClass2 : public cDoxyClass

{

public:

    int getNum(void) { return 2; }

};

--- class.cpp의 코드 ---

#include "class.h"

///////////////////////////////////////////////////////////////////////////////

// Doxygen 예제용 클래스

//! 생성자

cDoxyClass()

{

    m_nNum = 0;

}

//! 소멸자

~cDoxyClass()

{

}

//! @brief 질문 메세지 박스 출력

bool showQuestionBox(

     const TCHAR* msg            //!< 질문 내용

    , const TCHAR* title = NULL    //!< 메세지 박스 제목

    )

{

    m_nNum++;

    if ( IDYES == MessageBox(NULL, msg, title, MB_YESNO | MB_ICONQUESTION | MB_TOPMOST) )

        return true;

    return false;

}

//! 메세지 박스 출력 횟수 얻기

//! @return 메세지 박스 출력 횟수

int getNum(void)

{

    return m_nNum;

}

------

※ 주의사항 : 한글을 혼용하기 위해서 UTF-8로 소스를 작성하시는 것이 좋습니다. 그리고 UTF-8로 비주얼 스튜디오에서 작업하실 때 파일 첫부분에 빈공백을 넣어주어야 정상적으로 작동하는 것을 확인했습니다.

VS2005의 UTF-8 저장하는 법

Visual Studio .NET 2005에서는 파일 메뉴의 저장 고급 옵션에서 파일의 형식을 선택할 수 있습니다. 예전엔 ANSI 파일 말고는 읽지도 못했는데 엄청난(남들 다 하지만 MS는 안하는?) 발전이라고 할 수 있겠습니다. 여기서 서명있는 UTF-8 형식을 선택하면 이후부터 해당 파일은 UTF-8로 저장됩니다.
 그러나 UTF-8은 분명 자동인식 할 수 있는 형식임에도 불구하고 다른 편집기에서 저장한 서명없는 UTF-8 문서는 읽지 못하는 고지식한 면을 보이기도 합니다. 이럴 때는 별 수 없이 ANSI로 다시 저장하고 VS2005에서 읽은 후 서명있는 UTF-8로 바꿔줘야 합니다.
 그리고 이 UTF-8 서명 때문인지 소스 파일의 첫줄에 빈줄을 넣어주어야 Doxygen이 문제없이 인식합니다.

3. 문서 생성 - Step1
 자 위의 소스가 작동하는지 안하는지는 머리 아프게 고민하지 말고 바로 문서를 만들어 보도록 하겠습니다. 우선 DoxyWizard를 실행합니다.

  Wizard 버튼을 눌러서 몇가지 설정을 따라합니다.

Wizard 설정

프로젝트 이름과 버전 혹은 코드명을 적고,
소스코드의 최상위 디렉토리를 선택합니다. (나중에 개별로 추가도 가능합니다.)
그리고 Scan recursively를 체크해서 하위 디렉토리까지 찾도록 했습니다.
마지막으로 문서가 생성될 위치를 선택합니다.

우선 C++ 출력에 최적화 시켰습니다.

출력은 웹문서로만 하게 선택했습니다.(PHP가 된다면 검색도 달아줍니다!)
PDF로도 출력이 가능합니다.

GraphViz로 각종 다이어그램도 추가했습니다.

OK 버튼을 누르고 나면 대다수 설정을 마쳤습니다. 추가로 몇가지 설정을 더 살펴보고 문서를 생성하도록 하겠습니다.

 Expert 버튼을 눌러서 고급 설정으로 들어갑니다.

Expert 설정

Project 탭입니다. 문서 프로젝트의 전반적인 옵션을 설정합니다.
우선 손상된 한글을 고쳐주고 OUTPUT_LANGUAGE를 Korean으로 바꿔줍니다.

그리고 아래쪽으로 내려가면 파일이름을 표시할 때 앞쪽의 긴 디렉토리명을 떼어낼 수 있도록 STRIP_FROM_PATH라는 옵션에 상위 디렉토리를 추가해줍니다.

SHORT_NAMES라는 옵션을 체크하지 않으면 GraphViz에서 오류를 발생시킬 수도 있습니다.

Build 탭으로 이동하면 좀 더 세부적인 옵션들이 있습니다.
EXTRACT_ALL과 EXTRACT_ANON_NSPACES를 체크하지 않으면 네임스페이스에 속하지 않은 함수나 구조체들이 포함되지 않을 수 있습니다.

Input 탭에서는 소스 파일이 있는 디렉토리를 별도로 추가할 수 있습니다.

Source Browser 탭은 문서에 소스를 어떻게 포함시킬지 결정합니다.
SOURCE_BROWSER 옵션에 체크를 하면 문서에 컬러링과 링크를 제공하는 소스 전체를 포함시켜 주기 때문에 문서에서 바로 소스를 확인할 수 있습니다.
그리고 VERBATIM_HEADERS를 사용하면 cpp와 같은 소스를 포함하지 않고 헤더 파일의 소스만 포함시켜서 라이브러리 등을 전달하고자 할 때 꽤나 유용합니다.

HTML 탭에서 생성되는 웹문서의 옵션을 선택할 수 있습니다.
GENERATE_TREEVIEW 옵션을 체크하면 좌측에 프레임으로 이루어진 트리뷰를 추가해 줍니다.
Dot 탭에서는 포함될 각종 그래프 옵션을 설정할 수 있습니다.
특히 CLASS_DIAGRAMS 옵션은 꽤나 유용하므로 체크해서 사용하시면 좋습니다.

물론 설치된 GraphViz의 위치를 설정해주는 것도 잊으시면 안됩니다.

OK 버튼을 눌러서 설정을 적용합니다.
소개된 것 외에도 많은 옵션이 있으므로 Doxygen 문서를 확인하시면서 이것저것 시도해서 확인해 보시는 것도 좋습니다.

4. 문서 생성 - Step2
 우선 설정 파일을 저장해야 합니다. doc 디렉토리를 만들고 Save 버튼을 눌러서 그곳에 저장하겠습니다.

그러면 상태가 '저장됨'으로 바뀝니다.

저장하지 않으면 문서를 생성할 수 없을 뿐더러 아무 경고 없이 이제까지 한 설정이 날아갈 수도 있습니다. 물론 한번 저장해둔 설정은 Load 버튼으로 언제든지 다시 불러서 계속 생성할 수 있습니다.

5. 문서 생성 - Step3
 Doxygen이 작업할 디렉토리를 선택합니다. 로그 파일이나 생성 중의 중간 파일 등이 사용할 위치입니다. 그냥 doc 디렉토리를 선택하겠습니다.

6. 문서 생성 - Step4
 Start 버튼을 눌러서 최종적인 문서를 생성합니다. 만약 오류가 있었다면 로그창에 표시됩니다. 그러면 해당 오류 부분을 바로잡아 주고 다시 생성하면 됩니다. 소스 코드에는 어떠한 위해도 가하지 않으므로 Doxygen의 오류 코드를 심각하게 걱정할 필요는 없습니다. 제 경험상으로는 GraphViz와의 오류가 많았습니다만 한번 작동하는 옵션 조합을 발견하고 나면 문제없이 잘 작동했습니다. SHORT_NAMES라는 옵션을 한번 확인해 보시기 바랍니다.

7. 문서 확인
 바야흐로 생성된 문서의 결과를 확인할 때가 되었습니다. 작업 디렉토리로 선택했던 doc 디렉토리를 보면 html이라는 디렉토리가 생성되었을 것입니다. 이 디렉토리 안의 index.html을 열어서 확인해 보겠습니다.

클래스 계통도까지 삽입되어서 매우 깔금한 문서가 만들어 졌습니다. (그런데 프로젝트 제목의 한글 부분은 손상되었군요. 프로젝트 제목은 한글로 입력하면 안되겠습니다.)

그리고 VERBATIM_HEADERS 옵션을 사용했기 때문에 헤더 파일의 전체 코드가 포함되었습니다.

DoxyWizard의 사용법을 중심으로 Doxygen 사용법을 알아보았습니다.
많은 분들이 Doxygen을 사용하여 문서화의 작업 시간을 단축하셨으면 하는 바램입니다.

 

출처 : http://blog.tinywolf.com/2