Doxygen 설치

Doxygen이 문서화에 편한다고 말은 많이 들었는데, 내 자신이 필요성을 인식하지 못하였기 때문에, 수작으로 워드로 작성하는게 더 좋다는 생각을 해왔다. GpgStudy 포럼에서 여러 사람이 추천하니, 맛이나 한번 봐야겠다는 생각에 이문서를 작성한다.   

평소에 개발관련 책을 많이 읽고 개발자 커뮤니티도 열심히 읽고 느끼기는 하지만, 프로젝트가 막상 시작되면, 일정에 쫓겨 많은 것을 적용하지 못하는 실정이다.

자!!! 본론으로 들어가자.
Doxygen 설치 뿐 아니라 관련 툴도 같이 설치한다.

설치

1. graphviz 다운로드: 추가로 위에 있는 그래픽 툴은 doxygen의 계층 구조 그래픽을 그려준다
http://www.graphviz.org/Download_windows.php

2. doxygen: 프로그램 소스를 문서화 해주는 프로그램
chm 파일 등의 문서로 만들때는 HTML Help Workshop 필요하다.
 http://www.stack.nl/~dimitri/doxygen/
다운로드 메뉴로 이동한다.

3. KingsTools:  Doxygen을 비쥬얼 스튜디오에서 편리하게 사용하기 위한 애드인 프로그램
http://www.codeproject.com/macro/KingsTools.asp

Doxzygen 실행

문서를 생성하기 위한 방법은  3가지가 있다.

1. Wizard: 손쉽게 몇가지 옵션만 조정하여 문서를 Export 할 수 있다.
2. Expert: 자신만의 문서 포맷이나 자세한 설정이 필요한 경우 사용한다.
3. Load: 저장된 파일을 불러와서 사용하는 경우이다.

 

1. Wizard로 실행

위자드를 실행하면 Project 탭이 활성화되어 메뉴가 뜬다.

프로젝트 네임이나 폴더이름을 한글을 사용하게 되면 Doxygen에 의한 변환이 제대로 되지 않을것이다.
한글을 사용하면 Doxygen에서 해괴 망칙한 에러메세지가 나올 것이다.

"Project name"과 "Project version or id" 적당한 이름을 적어준다.
"Source code directory"에 소스 코드가 있는 폴더를 지정해 준다.
"Scan recursively" 여기를 체크하면 하위 폴더까지 포함하게 된다.
"Destination directory" Export 할 문서의 위치를 지정한다.

"Documented entities only" 문서화 태그가 있는 부분만 문서화 된다. 이 옵션을 선택하면 EXTRACT_ALL,
EXTRACT_PRIVATE, EXTRACT_STATIC 옵션이 제거된다.

"All entities" 모든 부분을 문서화 한다. 보통은 All을 선택한다.

"include cross-referenced source code in the output"  인터넷을 하다보면, 왼쪽에 라인넘버가 있는 소스를 본적이 있을 것이다. 문서와 함께 소스를 바로 참고 할 필요가 있을 때 이 옵션을 체크한다.
이 옵션을 체크하면 SOURCE_BROWSER 옵션이 설정된다.

"Optimize for C++ output" 해당하는 언어를 선택한다.

문서를 익스포트 할 때, 어떤 포맷으로 저장할지 정한다.
보통은 "HTML", "plain HTML"옵션을 선택한다...

"with frames and a navigation tree" plain HTML 기능에 MSDN 온라인처럼 트리 기능을 보여준다.
나머지 기능은 입맛에 맛게 테스트 해보도록.......

참고 <CHM 파일 만들기>

prepare for compressed HTML (.chm)로 익스포트 하면 chm 파일을 만들기 위한 html 파일로 만들어 준다.
chm 파일로 만들기 위해서는 MS사의 Help WorkShop이 필요하다.(물론 무료)

HTML Help Workshop을 실행하여 [File/Open] 메뉴를 실행하여 Doxygen에 의해 만들어진 HTML 폴더로 이동한다.
폴더로 이동하여 index.hhp (HTML Help Workshop Project 파일) 파일을 열기

[File/Compile] 메뉴에서 컴파일을 실행하면, chm파일이 생성된다..

GraphViz툴이 설치 되었다다면 빨간 네모안의 모든 옵션들을 선택한다.
"Call graphs"옵션이 선택 되었을 때와 안되었을 때의 차이점을 아직 모르겠다... 아시는분은 연락을.....ㅠ.ㅠ

모든 옵션을 조정 했으니 "OK"버튼을 눌러서 Doxygen 메인 상자로 나온다.
Step 2로 가서 설정 파일을 Save 한다.

Step 3으로 가면 Doxygen의 실행에 관련된 폴더를 지정하라고 한다.
 적당히 지정하고 넘어간다.

자 이제 실행 고우 고우 고우~~~

Step 4로 가면 "Start" 버튼이 보인다"   빡시게 눌러보자.


2. Expert로 실행

전문가 모드로 실행하면 17개 가량의 탭으로 인해 머리가 아파 올 것이다..
자주 사용되는 것은 Project, Build, Input, Source Browser, Dot 탭이다.

<Project 탭>
BRIFT_MEMBER_DESC : 멤버 리스트 뒤에 멤버 각각에 대한 자세한 설명을 문서화 할지 여부.

REPEAT_BRIEF:
BRIFT_MEMBER_DESC 옵션이 ON시 이 옵션이 ON일때는 멤버에 대한 설명이 클래스 개요, 멤버 설명 부분 모두 나옴
BRIFT_MEMBER_DESC 옵션이 OFF시 이 옵션이 ON일때는 멤버에 대한  설명이 멤버 설명 부분에만 나옴
HIDE_UNDOC_MEMBERS와 BRIFT_MEMBER_DESC 옵션 둘다 OFF일때는 이 옵션은 영향을 미치지 못한다.

ALWAYS_DETAIL_SEC:  항상 상세정보를 보여준다. REPEAT_BRIEF가 같이 켜지면 상세정보가 없어도 영역을 할당한다.

INLINE_INHERITED_MEMB: 생성자와 소멸자를 제외한 상속된 모든 정보를 보여준다.

JAVADOC_AUTOBRIEF: QT 스타일 대신 자바스타일의 주석을 BRIEF로 해석한다.  C++ 코드의 경우 체크하는 것이 좋으며, 이 옵션이 꺼지면 BRIEF가 멀티 라인으로 나타나지 않는다.

SEPARATE_MEMBER_PAGES: 클래스와 오퍼레이션들의 설명이 있는 페이지와 분리한다.

TAB size는 보통 8로 사용하는 것이 보기에 좋다.

<Build 탭>

EXTRACT_ALL:
클래스의 모든 멤버를 문서화 한다.
단 EXTRACT_PRIVATE와 EXTRACT_STATIC이 체크되지 않는다면 주석없는 멤버는 보이지 않는다.

EXTRACT_LOCAL_CALSSES: 체크하지 않으면 헤어데 있는 클래스만 문서화 된다.

HIDE_UNDOC_MEMBERS: 주석없는 멤버는 보여주지 않는다.

HIDE_UNDOC_CLASSES: 주석없는 클래스는 보여주지 않는다.

HIDE_IN_BODY_DOCS:   함수의 안쪽에 있는 주석을 모두 보여주지 않는다.

SORT_MEMBER_DOCS: 멤버를 알파벳순으로 보여준다.

GENERATE_TODOLIST: 문서화에 "관련된 페이지" 탭이 추가 되고 그 탭에서 todo tag 들만 모아서 보여주는 페이지를 생성해준다. 클래스 설명에 todo tag를 넣으면 유용하다.

GENERATE_TESTLIST: 위와 마찬가지로 test태그의 내용만 보여주는 페이지가 추가된다.

GENERATE_BUGLIST: 마찬가지로 bug 태그의 내용만 보여주는 페이지가 추가된다.

<Input 탭>

문서화할 대상을 선택한다. Wizard를 이용할 경우 폴더만 선택할 수 있지만 여기서는 특정파일만 복수개로 선택할 수도 있다. 물론 폴더 선택도 가능

<Source Browser 탭>

SOURCE_BROWSER: 소스파일의 리스트를 생성한다. 만약 문서화 소스를 상호 참조하고자 한다면 체크한다. 단 지저분해질 수도 있다.

INLINE_SOURCES: 문서화에 구현파일의 내용도 포함한다. C++이라면 CPP 파일도 문서화에 포함된다. 만약 보안상 CPP 파일을 공개 하지 말아야 한다면 체크 하지 말 것.

<Index 탭>

ALPHABETICAL_INDEX: 알파벳 순서로 클래스들의 인덱스를 만든다. 클래스들의 brief를 표시하도록 설정했다면 클래스의 brief가 알파벳순으로 나오므로 굳이 이 옵션을 쓸필요 없음.(좀 지저분함)

<HTML 탭>

GENERATE_HTML: 문서를 HTML 형식으로 생성한다.

GENERATE_HTMLHELP: chm 파일 형식으로 만든다. 문서화를 도움말 ㅎ여태의 파일로 배포하려면 체크.

<LaTex 탭>

수학 서식표현등에 적합한 LaTex 포맷으로 문서를 생성할 경우 사용

<RTF 탭>

word같은 RTF 포맷을 생성할 경우 사용

<Preprocessor 탭>

doxygen이 소스코드를 문서화 하기 전에 소스코드와 관계하는 파일들을 미리 처리하도록 하는 기능.
문서화에 포함하지는 않지만 문서화 하는 소스파일들과 연관성이 있는 파일들을 포함 시킨다.

<Dot 탭>

클래스에 대한 참조와 구조의 그래프를 보여주고 싶다면 GraphViz의 Dot를 Doxygen에 설치하기를 권장한다.
먼저 GraphViz를 설치한 다음 이 탭에서 설정을 해야만 문서에 그래프가 나타난다.

DOT_PATH: Dot가 설치된 폴더의 bin 폴더의 bin 폴더의 절대경로를 지정해준다. 그 다음 HAVE_DOT를 꼭 체크한다.

CLASS_DIAGRAMS: 클래스의 상속 구조를 보여준다.

INCLUDE_GRAPH: 클래스의 include 종속성을 그래프로 보여준다.

GRAPHICAL_HIERARCHY: 그래프를 text가 아닌 그래픽 버전으로 보여준다. 당근 필수 체크.

UML_LOOK: UML 형식으로 보여준다. 이걸 체크하면 컴파일 시간과 용량이 무지하게 증가하므로 신중히 선택 할 것.

INCLUDE_GRAPH: 파일들의 include 구조를 그래프로 보여준다. 매우 유용.

DOT_IMAGE_FORMAT: 그래프들을 모두 이미지 파일로 생성한다. 이미지 퐴ㅅ을 선택. png, jpg, gif 중 하나 택일.
(사진이 아니므로 png나 gif가 jpg 보다 나은 품질과 효율을 보인다.)


펌 링크:

아래 링크의 내용를 가져와 위자드 관련쪽만 약간 편집하고, 전문가 모드는 거의 복사했음http://blog.naver.com/koreteck/39156360

KingsTools 사용법
http://blog.naver.com/bastard9/140038592188