Doxygen 을 이용한 Java API Documentation 작성하기

Java JDK 속에는 javadoc.exe 라는 Java API 문서 생성기가 들어있다. 이 유틸리티를 이용하면 HTML 형식의 문서를 쉽게 작성할 수 있다. 더구나 Eclipse 에 내장돼있기 때문에 Command Line 명령어를 입력하지 않고서도 편하게 API 문서를 작성할 수 있다.
참고> http://www.javaexpert.co.kr/19  , http://www.javaexpert.co.kr/20
반면, Doxygen 이라는 툴은 Java 뿐만 아니라, 다른 언어 즉 C 나 C++, 파이썬, PHP 용 API 문서를 생성시켜준다. 문론 HTML 형식으로 말이다. 자 이번 칼럼에서는 Doxygen 을 이용해서 편하게 Java API 문서를 작성해 보자.

먼저, Java API Documentation 할 문서는 아래와 같다.

<참고 사이트>
1. http://woohaha.egloos.com/260149
2. http://blog.daum.net/_blog/BlogView.do?blogid=03Mer&articleno=10061768&_bloghome_menu=recenttext#ajax_history_home
3. http://www.stack.nl/~dimitri/doxygen/install.html
4. http://blog.naver.com/turbo93?Redirect=Log&logNo=50003087613

일단 툴을 다운로드받자. 사이트의 주소는 아래와 같다.
http://www.stack.nl/~dimitri/doxygen/

왼쪽 프레임의 [Download] 링크를 클릭한다.

현재 최신 버전은 2008년 12월 27일에 Release 된 1.5.8 이다. 해당 플랫폼별로 다운 받으면 된다. 여기서는 Windows 버전으로 설명하겠다. [doxygen-1.5.8-setup.exe (7.2M)] 를 ftp 이든 http 이든 링크를 클릭하여 다운받자.

다운로드받은 파일 [doxygen-1.5.8-setup.exe] 를 더블클릭하여 설치하자.

설치자체는 어렵지 않다. 계속 다음버튼을 클릭만 하면 된다. 자 이제 실행해보자.
시작 -> 모든프로그램 -> doxygen -> doxywizard 를 클릭하면 아래의 그림처럼 실행된다.

[Doxygen GUI frontend] 창에 있는 Step 순서대로 설정하면 Doxygen 문서가 생성된다. 먼저 Step 1 부터 보자.  
Step1. doxygen 이 실행할 작업 디렉토리를 지정한다. [Select...] 버튼을 클릭하자.

필자는 C:\JavaRoom 디렉토리를 선택했다. [확인] 버튼을 클릭하자.

Step2. 문서를 생성하기 위한 각종 옵션을 설정한다.
기본은 [Wizard] 탭이 선택돼 있다. 계층이 Project, Mode, Output, Diagrams 로 돼있다.

기본적인 프로젝트에 대한 정보를 설정하는 곳이다. 각 필드에 들어가는 내용은 아래와 같다.
Project name : 프로젝트의 이름
Project version or id : 프로젝트 문서 버전
Source code directory : 소스 코드 문서 자동 빌드 작업을 할 디렉토리 경로를 지정
Scan recursively : Source code directory 의 하위 경로까지 소스 코드 문서 자동 빌드 작업을 할 것이지의 여부, 체크하면 하위 디렉토리까지 포함한다.
Destination directory : 생성된 소스 코드 문서가 저장될 디렉토리

필자는 아래의 그림과 같이 간단하게 설정했다. [Next] 버튼을 클릭하자.

Mode 에서는 대상 소스 코드의 언어와 문서 생성 모드를 결정한다.

Documented entities only 를 선택하면 코드에서 문서화태그가 있는 부분만 문서화된다.
All entities 를 체크하면 코드의 모든 부분을 문서화 한다. Doxygen 주석이 없는 경우 설명이 없이 네임스페이스, 클래스, 메소드 등만 나타난다. 특별한 이유가 없다면 All entities 를 선택한다.
Include cross-referenced source code in the output 을 체크하면 실제로는 SOURCE_BROWSER 옵션이 설정된다. 이 옵션이 설정되면 문서화된 코드의 entity 들이 실제 코드 어디에 해당하는지 그 링크를 보여준다. 문서가 좀 지저분해지는 경향이 있지만 문서를 보면서 해당 소스코드를 바로 참고할 필요가 있다면 선택한다.
[Select programming language to optimize the results for] 당근 Java 를 선택한다.
필자가 선택한 설정은 아래 그림과 같다.

[Next] 버튼을 클릭하자.

Output 에서는 출력될 format 을 지정한다.
HTML : HTML 형태로 출력할지의 여부
plain HTML :  단순한 HTML 형태로 출력
with frames and a navigation tree : Navigation Tree 와 Frame 으로 출력
prepare for compressed HTML(.chm) : Windows Help 파일 제작을 위한 파일 생성
with search function (require PHP enabled web server) : function search 기능 포함 여부
LaTeX : LaTeX 형태로 출력할 지의 여부, 수학 기호등을 깔끔하게 표현할 경우 체크한다.
as intermediate format for hyperlinked PDF :  hyperlink 로 연결된 PDF 문서 생성을 위한 LaTeX로 출력
as intermediate format for PDF : PDF 문서 생성을 위한 LaTeX 로 출력
as intermediate format for PostScript : PostScript 생성을 위한 LaTeX 로 출력
Man pages : Unix 의 man 명령 형태의 출력 여부
Rich Text Format(RTF) : Rich Text 형태의 출력 여부
XML : XML 형태의 출력 여부

필자는 LaTeX 에서 [as intermediate format for PostScript] 를 선택했다. [Next] 버튼을 클릭한다.

마지막으로 Diagram 이다. 이 곳은 생성할 Diagram 의 표시 형태를 결정한다.
No diagrams : Diagram 을 생성하지 않는다.
Use built-in class diagram generator : Doxygen 에 내장된 class diagram generator 로 diagram 을 생성
Use dot tool from the GraphViz package to generate : GraphViz 를 이용한 diagram 생성(이 기능은 이미 GraphViz 가 설치돼 있어야 사용할 수 있다.)
아래의 그림처럼 필자는 GraphViz 를 사용하며 아래의 모든 체크박스를 선택했다.

[Expert] 탭을 선택하기 전에, 먼저 GraphViz 툴을 설치하자.
다운로드의 사이트는 아래와 같다.
http://www.graphviz.org

왼쪽 프레임의 [Download] 링크를 클릭하자.
[Agree] 버튼을 클릭한다.

각 플랫폼에 맞게 다운로드할 수 있다. 우리는 Windows 링크를 클릭한다.

[graphviz-2.20.3.msi] 링크를 클릭해서 다운로드하자.

설치는 간단하다. 다운로드 받은 파일을 더블클릭하여 실행하고 [Next]버튼을 클릭하기만 하면 된다.

자 다시, Doxygen 창으로 돌아가서, [Expert] 탭을 클릭한다.

해당 글자위에 마우스를 올려놓으면 왼쪽 하단프레임에 설명이 나타난다.
[Project] 계층에서는 아래의 사항을 체크했다.
ALWAYS_DETAIL_SEC : 항상 상세정보를 보여준다. REPEAT_BRIEF 가 같이 켜지면 개략 정보가 없어도 상세정보 영역을 생성한다.
INLINE_INHERITED_MEMB : 상속된 모든 멤버들도 보여준다. 단, 생성자와 파괴자 제외.
JAVADOC_AUTOBRIEF : QT스타일 대신 자바스타일의 주석을 BRIEF 로 해석한다. C++ 코드의 경우 체크하는 것이 좋으며, 이 옵션이 꺼지면 BRIEF 가 멀티라인으로 나타나지 않는다.

[Build] 계층에서는 아래의 사항을 체크했다.
EXTRACT_ALL : 클래스의 모든 멤버를 문서화한다. 단 EXTRACT_PRIVATE 과 EXTRACT_STATIC 이 체크되지 않는다면 주석없는 멤버는 보이지 않는다.

[Dot] 계층에서는 아래의 사항을 체크했다.
먼저, DOT_PATH설정을 하자. 보통 GrahphViz 설치된 경로에서 bin 디렉토리를 지정하면 된다. 그리고 나서, 반드시 HAVA_DOT 을 체크해야 한다.
CLASS_DIAGRAMS : 클래스의 상속구조를 보여준다.
GRAPHICAL_HIERARCHY : 그래프를 text가 아닌 그래픽 버전으로 보여준다. 당근 필수 체크
UML_LOOK : UML 형식으로 보여준다. 이걸 체크하면 컴파일 시간과 용량이 무지하게 증가하므로 신중히 선택할 것.
INCLUDE_GRAPH : 파일들의 include 구조를 그래프로 보여준다. 매우 유용.

 

이제 [Run] 탭을 클릭하자.
실행하기 위해 [Run doxygen] 버튼을 클릭한다.

잠시후, 아래의 그림처럼 결과가 나타나게 된다.

그럼, [Show HTML output] 버튼을 클릭하여 브라우저를 통해 API 문서를 확인해 보자.

이상 강의끝...