프로젝트 문서화 툴 Doxygen 그리고 DoxyComment

▶ 프로그램 다운 로드 (약 5.25MB)

http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc

▶  설명

프로젝트를 자동으로 문서화 (html/latex/pdf) 해주므로 주석작업과 문서화를 동시에 할 수 있다. 또한 도움말형태의 결과물을 얻을 수 있기 때문에 별도의 작업으로 인한 결과물보다 큰 효과를 볼 수 있다.

▶  설정밥법( Ver 1.5 )

1. Doxygen 실행 -> Wizard 선택

 하위 폴더가 있을 경우 Scan recursively를 체크할 것  해당 언어에 최적화 시킨다.( Doxygen이 자동으로 세부옵션을 설정해준다. ) 
 필요한 문서 형태만 체크해둔다.  

         TIP) .chm으로 선택했을경우

 Expert->Html에서 HHC.exe(MS HTML Help Compiler )경로를 설정해줘야 한다.  
 나열되어있는 diagram이 문서에 자동으로 생성되게 할 수 있다.다만 GraphViz( http://www.graphviz.org/ ) 가 필요하며 문서생성 속도가 매우 느려진다. 최종 완성 소스에서만 체크하는게 좋다.  

 

2. Wizard로 기본적인 설정을 하고 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의 위치를 설정해주는 것도 잊으시면 안됩니다.

   

3. 설정한 Doxyfile 을 저장(Save)하고 Working directory 를 지정한 다음 Start 시키면 된다.

 

 

해당 디렉토리에 문서폴더가 생성된것을 확인할 수 있다. Index를 실행하여 확인해보자.

 

*Doxygen 기본 스타일
   /** */
*주석안에 아이템들
@brief : 간략한 설명
@remarks : 자세한 설명
@class : 클래스명
@file : 파일 이름을 구별할때.
@return : 함수의 리턴값 나타낼때.
@author : 작성자 이름을 나타낼때
@date : 작성날짜를 나타낼때.
@param : 함수 파라메터를 나타낼때
@see : 참고할 함수나 클래스, define 등을 지정한다.
@image : 이미지 추가
@todo
@bug
@code ==>중요 코드를 설명할때 시작 지점 가리킨다.
@endcode ==> 중요코드 설명할때 종료 지점 가리킨다.
@exeception
@mainpage
@section
@warning
@defgroup 그룹이름 : 그룹정의
@addtogroup 그룹이름 : 정의 된 그룹에 추가
\{, \} : 그룹화할 코드의 시작과 끝
@par : brief, return 말구 다른 항목을 문서화 할때


 ====클래스 처리===
 @class ==> 클래스명 나타낼때.
 *클래스 멤버에대한 처리
 /// :  멤버 상단에
 /**< 내용 */ :  멤버 옆에
 ///< : 멤버옆에

===중요 코드도 주석을 단다.===
@code 로 시작해서
@endcode 로 끝낸다.
 예제)
     /**
      * @brief 예제코드
      *
      *  추가설명
      * @code
        *........
        * @endcode
      */

▼ 주석 1

 

int GlobalVal;       ///< 전역 변수

 

 

/** \brief

        문자열 바꾸기

    \remarks

        입력된 문자열에서 원하는 문자열을 찾아 바꾼다.

    \return

        마지막으로 찾은 문자열의 첫번째 주소값을 반환한다.

*/

char *

Replace(

        char * pStr,     ///< 입력 문자열

        char * find,     ///< 찾을 문자열

        char * replace       ///< 변경할 문자열

        )

{

    ...

}

  

▼ 주석 2

또한 메인페이지(MainPage)를 두어 프로그램의 전체 개요 등을 적어줄 수 있다.

 

/** \mainpage Doxygen Test

    \section developer 개발자

        - 이상호

        

    \section info 개발목적

        - Doygen 문서 테스트용 소스

 

        

    \section advenced 추가정보

        - 글머리는 '-' 태그를 사용하면 되며

            - 탭으로 들여쓸경우 하위 항목이 된다.

        -# 번호매기기는 '-#' 방식으로 할수 있다.

            -# 위와 같이 탭으로 들여쓸경우 하위 항목이 된다.

            -# 두번째 하위 항목

            

        

        - 이런식으로 그림을 넣을수도 있다.

                

        \image html gom.jpg

*/

  

▼ 주석 3

함수나 데이터 구조의 경우 파일 단위가 아니라 특정 기능에 따라 분류해주고 싶을 경우 모듈 설정을 할 수 있다.

 

 

/**

    \defgroup string 문자열 관련 모듈

    \defgroup date       날짜 관련 모듈

*/

 

위와 같은 방식으로 그룹을 정의한 다음 해당 함수나 데이터 구조 코드의 위아래에 다음과 같은 코드를 삽입하면 된다.

 

 

/**

    \addtogroup  string

    \{

*/

...

그룹화할 함수나 데이터 구조 코드

...

/** \} */

  

 

▼ 주석 4

\brief 나 \return 등이 보여주는 항목 이외에 다른 항목을 쓰고 싶다면 \par 명령어를 사용하면 된다.

 

/** \brief

        현재 시간을 얻는다.

    \remarks

        ST_TIME 구조체 형식으로 현재 시간을 얻는다.

    \par 요구사항

        time.h 선언이 필요하다.

    \return

        성공시 0을 반환한다. 에러가 발생하면 -1을 반환한다.

    \author

        이상호

*/

void

GetLocalTime(

              ST_TIME * today

              )

{

...

}

  

 

 

Doxygen의 문법은 KLDPWiki를 참고

한글이 깨져  있다면 Expert ->Input 탭의 INPUT_ENCODING를 UTF-8에서 EUC-KR 또는 cp949로 변경후작업하자.. 아니면 VS2005에서 저장 고급옵션에서 UTF-8로 파일을 저장해 줘야 하는데이는 프로젝트 파일이 많으면 곤란하다. 파일마다 해줘야 하므로

DoxyComment add-in for Visual Studio 2005

DoxyComment 는 Doxygen처럼 문서화까지 해주지는 않고 소스 코드상에 주석만 달아주는
Add-in 이다. 

위 그림처럼 버튼이 추가 되는데.. 코드 주석 추가를 누르면 그냥 주석 추가되는정도..

아래는 cafe.naver.com/devrookie 에서 민군님이 올리신 내용이다.
관련 파일은 첨부파일에

설치하시면 주석달 때 Default로 장문의 주석이 달리는데.

주석양식을 커스텀마이징 할수 있습니다.

예전 KingsTools 형식으로 간략하게 커스텀마이징 한 Provider를

만들어 두었습니다.

“C:\Program Files\SourceForge.net\DoxyComment\Custom Providers”

폴더를 생성하시고. (원래는 폴더가 없음)

첨부된 “MinProvider.dll”을 카피해 주시면 됩니다.

그후 “Tools – Option – DoxyComment” 에서 MinProvider를 선택해주시면 됩니다.
원문 : http://cafe.naver.com/devrookie.cafe?iframe_url=/ArticleRead.nhn%3Farticleid=293

쩝.. DoxyComment 는 별로인것 같다.. 그냥 비쥬얼어시스트의 Snippet(구버젼 VA에서는 AutoText)
를 쓰는게 좋겠다.. 아님 직접 치던가...

기타 html 파일을 chm 파일로 바꿔주는 놈..
HTML Help 1.4 SDK

마지막으로 Doxygen 작업의 기본 원칙이라는 글이다..

1          기본 원칙

1.1     주석작성의 목적은 자기 자신뿐만이 아니라 다른 사람들을 위한 작업이다.
(따라서 자기만 알아볼 수 잇는 약어를 사용하거나 농담으로 주석을 작성하면 안된다.)

1.2          주석은 모국어로 기입한다.
(아무리 타국어를 잘하는 사람이라도 모국어보다 타국어를 잘할 수 없다. 또한 다른 사람들을 위한 배려이다.)

1.3          주석은 항상 최신으로 유지가 되어야한다.
(코드를 변경한 이후에는 반드시 관련 주석을 함께 변경해야한다. 최신이 아닌 주석은 오히려 코드 분석에 큰 방해가 된다.)

1.4          헤더파일의 손상을 최소화한다.
(헤더파일은 개발자가 가장 자주 접근하는 파일이다. 무분별한 여러라인의 주석추가로 인하여 헤더파일 자체의 분석능력을 떨어뜨리다면 개발자는 결국 열기 불편한 문서파일만 접근하게 될것이다.)

1.5          중복된 주석 입력 작업은 최소화 한다.
(함수의 인자를 설명하기 위해서 그 인자를 중복해서 입력할 필요는 없다. 동일한 클레스 멤버 함수의 설명주석을 헤더와 구현 파일에 중복하여 기입 할 필요가 없다. 불필요한 중복된 주석입력 작업은 주석입력을 꺼리게 만드는 계기가 된다. 단 클래스와 같이 중요도가 매우 높은 항목은 예외로 한다.)

1.6          Doxygen은 파일, 클래스, 구조체, 멤버변수, 멤버함수, 일반함수등에만 사용한다.
(Doxygen의 모든 문법과 방법을 사용하여 너무 많은 활용을 하는 것은 오히려 코드가 보기 좋지 않고 가독성이 떨어지게 된다.)

1.7          함수의 주석은 동사로 끝을 맺고 변수나 인자, 객체의 주석은 명사로 끝을 맺는다.
(함수는 행위를 나타내고 변수는 객체를 나타내기 때문이다.)

1.8          무분별한 주석추가는 자제한다.
(아주 어려운 알고리즘이 아니라면 라인단위로 주석을 다는 것은 코드의 가독성을 해치게 된다.)

1.9          주석 입력작업의 목적은 코드를 알아보기 좋게 하는 작업이므로 모든 사항을 지나치게 철저하게

          지킬 필요는 없다.