최근에 가까운 지인의 소개로 Doxygen을 사용하게 되었는데, 역시 문서 자료로서의 가치 뿐만 아니라 업무를 인수인계하는데에도 매우 편리하군요. 매우 유명한 프로그램이라 이미 웹에 많은 글이 올라와 있지만, 처음 접하시는 분을 위해 저의 경험을 정리해 보겠습니다.

Doxygen 문서 모습

우선 Doxygen으로 만들어진 문서의 모습을 보겠습니다. 아직 Doxygen의 다양한 문법을 모두 학습하지 못했기 때문에 단순한 모습만 보여 드립니다. 이점 양해를 부탁드립니다. ^^; 저는 html 파일로 만드는 것을 좋아합니다. 아무래도 친숙한 포맷이기 때문에 만만하거든요.

메인 페이지입니다. Doxygen으로 문서를 만들면 index.html 파일이 생기는데, 그 파일을 열면 출력되는 페이지입니다.

왼쪽에는 Doxygen의 문서를 조금 더 쉽게 찾아 다니며 볼 수 있도록 검색 트리를 제공하고 있고, 오른쪽에는 프로젝트를 설명하는 자세한 정보가 보여집니다. 출력되는 프로젝트 정보는 Doxygen을 위해 따로 다른 파일에 작성한 것이 아니라, 프로젝트를 위한 소스 파일 중에 프로젝트를 대표하는 파일에 아래와 같이 주석문으로 입력해 놓으면, 알아서 Doxygen이 위와 같은 문서를 만들어 줍니다.

잠시 그 부분의 주석문을 보시겠습니다.

/**
    @mainpage  Project : datfile_t
    @section intro 소개
        - 소개 : datfile_t는 텍스트 파일을 이용하여 문자열, 정수, 실수, Boolean 값을
                 구분자로 구별하면서 읽거나 쓸 수 있도로 처리한다.
        - 설명 : main() 함수에는 datfile_t를 이용하여 dat 파일 내용을 출력하는 예제를 포함
    @section   Program 프로그램명
        - 프로그램명  :   sample
    @section  INOUTPUT    입/출력 자료
        - INPUT :   test.dat
        - OUTPUT :  test.dat 파일에 저장된 정보를 화면에 출력
    @section  CREATEINFO      작성 정보
        - 작성자 :   장길석
        - 작성일 :   2009-04-09
    @section  MODIFYINFO 수정 정보
        - 2009-04-15:
            -# 섹션과 섹션 사이에 빈행이 필요 없도록 수정
            -# 데이터를 수정하는 함수 추가
                - dat_write_integer()
                - dat_write_real()
            -# dat_free() 에서도 dat_flush() 호출
    @subsection subsection-name 주의할 사항
        - dat 파일 작성 요령
        @code
# 1. 주석문은 '#'문자로 시작하며, 섹션과 구별자와 같은 행에서 사용할 수 없다.
[  section 1  ]             <-- 섹션은 '['와 ']'로 입력하며, 이름 앞뒤에 추가된 공백문자는 자동 제거 된다.
first sec=sec 1 one         <-- 구별자와 데이터는 '='로 구분되며,
# 주석 행                   
   [correct]
test1=one
                            <-- 빈 행은 자유롭게 추가할 수 있다.
        @endcode
        - 저작권    장길석
        - 외부공개 금지
*/

수 많은 주석문 중에 Doxygen으로 출력될 주석은 /** 으로 시작해서 */ 로 끝나는 주석입니다. 이외에도 한개의 행을 위한 /// 주석도 있습니다만, 이런 Doxygen 문법은 이번 글에서는 생략하겠습니다. 이것까지 자세히 말씀 드리면 간략히 알아 보는 글이 어지러워 질 수 있으니까요. ^^

헤더 파일에 정의한 struct 구조도 아래와 같이 정리하여 줍니다.

datfile_t라는 struct의 위치부터 내부 멤버 설명까지 자세히 보여 줍니다. 이 부분은 소스에서 아래와 같이 입력했습니다.

/// ini 파일을 처리하는 객체를 위한 구조체
typedef struct
{   /// datfile 정보 저장 파일이름
    char       *filename;
    /// INI 정보가 변경되었는지의 여부
    int         is_changed;
    /// 모든 섹션의 문자열
    tstrlist   *lst_sections;
} datfile_t;

구조체 뿐만 아리라 함수도 아래와 같이 그래프를 제공하면서 훌륭한 문서를 만들어 줍니다.

이 부분의 소스 부분도 보시죠. 위의 그림에서처럼 main()함수에서 호출하는 dat_create(), dat_free(), dat_read_integer() 의 모습이 보이시죠?

int main( void)
/**
    @brief    datfile_t 사용 예를 보여준다.

    본 예제를 실행하면 실행 파일과 같은 디렉토리에 있는.\n
    test.dat 파일의 데이터를 화면에 출력한다.
    @return 의미 없음
*/
{
    if  ( NULL == ( datfile = dat_create( "test.dat")))                         // datfile 생성
    {
    }
    else
    {
        printf( "----------------------------- %s\n", "일반적인 자료 읽기 테스트");

        printf( "int2  = %d\n" , dat_read_integer( datfile, "section 1", "int2"     , 99));
    }
    dat_free( datfile);

    return 0;
}

Doxygen 문서에 출력되는 문장이야 main() 밑에 있는 주석문으로 만들어 진다고 하지만 그림은 어떻게 만들어질까요? 네, Doxygen이 소스코드를 분석해서 알아서 만들어 줍니다. 좋죠? ^^

또한 Doxygen의 expert의 옵션을 조정하면 Doxygen 문서 안에 소스를 추가할 수 있습니다.

어떻습니까? 프로그램을 작성하면서 주석문을 충실히 작성하면, 이후에 Doxygen을 이용하여 이렇게 훌륭한 문서를 만들어 낼 수 있습니다. 따로 문서를 작성하 필요가 없으며, 따로 작성하여 프로그램 소스와 문서의 버전이 차이가 나는 것을 걱정할 필요가 없습니다. ^^

다음 시간에는 제가 Doxygen을 설치한 방법을 정리하여 올리겠습니다.

 

이 게시물을...