[Doxygen] Doxygen 사용법, 예제

Doxygen

참고

https://www.stack.nl/~dimitri/doxygen/manual/index.html : doxygen 메뉴얼

http://www.slideshare.net/arload/doxygen-33932243 : doxygen 사용법

 

테스트 환경

- ubuntu14.04 lts

- php

 

 

 

 

 

테스트 코드

Test.php, Etc.php, subFolder/Etc.php 를 만들었다. 코드는 별 거 없다.

 

 

 

 

 

 

 

 

 

Doxygen 이란?

doxygen는 코드상의 주석을 통해 문서를 만들어내는 프로그램이다. doxygen에 맞는 주석을 사용하면 따로 문서를 만들 필요 없이 주석만으로 문서를 만들 수 있기 때문에 문서 관리를 따로 할 필요가 없고 코드만 보고도 이해하기가 쉬워진다.

 

아래와 같이 html 문서를 만들 수 있다.

 

 

 

 

 

 

기본 주석법

doxygen이 인식하는 주석법은

/** * 주석 * * */

이런 식으로 /** 주석 시작시 *을 두번 써 줘야 한다.

이 방법 말고도 주석 법은 더 있다.

 

아래의 사이트를 보면 주석 방법에 대해 나와 있다.

https://www.stack.nl/~dimitri/doxygen/manual/docblocks.html#specialblock

 

 

 

클래스에 대한 주석

@brief	간략한 설명
@details	자세한 설명
@author	저작권자
@date	날짜
@version	버전

 

 

예

/**  *  * @brief 테스트를 위한 클래스이다.  * @details 내부에서 아무짓도 안한다.  * @author oncellboy  * @date 1234-12-12  * @version 0.0.1  *  */ class Test{ }

 

출력 문석

 

 

 

메소드에 대한 주석

@brief	간략한 설명
@details	자세한 설명
@param	파라미터
@return	반환
@throws	발생 예외

 

예

/**  *  *        @brief 메서드 간략 설명  *        @details 메서드 자세한 설명  *        @param string a 파라미터 번  *        @param string b  *        이거는 테스트 파라미터  *  *        @return mixed|boolean  *  성공시 숫자, 실패시 false 반환  *          *        @throws ValidException 나쁜짓하면 예외발생          *  */ public function add($a,$b) { $sum = $a + $b;     return $sum; }

 

출력 문서

 

 

 

기타 주석

주석	설명	작성 예	출력 예
@todo	todo todo 리스트를 따로 관리도 해준다.	@todo 다음주까지 해야할 업무	todo 리스트 관리 @todo가 작성된 해당 클래스와 메소드를 알수 있다.
@bug	bug bug 리스트를 따로 관리도 해준다.	@bug 반환이 언제나 false이다. 해결해야함	bug 리스트 관리 @bug가 작성된 클래스와 메소드를 알수 있다.
@see	참고나 이것 저것 보여 줘야 하는것	@see 그냥 이것저것 보여줘야하는 것
_____|______       |	표	First Header  | Second Header  ------------- | -------------  Content Cell  | Content Cell  Content Cell  | Content Cell
@li	리스트	@li list 1 @li list 2
[내용](링크주소)	링크 클릭시 링크를 연다.	[내 블로그](http://onecellboy.tistory.com)
@code @endcode	코드 표현	@code{.py}  #!/usr/bin/python  print "Hello World! 뜸금없는 파이썬 코드" @endcode
@ref class @ref namespace.class	참조 클래스 이름이나 네임스페이스가 포함되어 있는 경우 namespace.class 로 써준다. 참조 링크를 클릭시 해당 클래스의 문서 페이지로 이동한다.	@ref Etc @ret subFolder.Etc	subFloder.Etc 클릭시 해당 클래스의 문서 페이지로 이동한다.
@n	주석 내에서 new line(개행) 이다.	@see 개행할 것 @n 이다.

 

 

작성 예 전체

<?php     require_once './Etc.php';         /**  *  * @brief 테스트를 위한 클래스이다.  * @details 내부에서 아무짓도 안한다.  * @author oncellboy  * @date 1234-12-12  * @version 0.0.1  *  */ class Test{   public $test;        public function __construct() {   }       public function show() {   $etc = new Etc();   $str = $etc->getText();   print_r($str); }     /**  *  *        @brief 메서드 간략 설명  *        @details 메서드 자세한 설명  *        @param string a 파라미터 번  *        @param string b  *        이거는 테스트 파라미터  *  *        @return mixed|boolean  *  성공시 숫자, 실패시 false 반환  *          *        @throws ValidException 나쁜짓하면 예외발생          *  *  *  *  @todo 다음주까지 해야할 업무  *   *  @bug 반환이 언제나 false이다. 해결해야함  *  *  *  @see 그냥 이것저것  *  보여줘야하는 것  *  *          *        First Header  | Second Header  *        ------------- | -------------  *        Content Cell  | Content Cell  *        Content Cell  | Content Cell  *  *  @li list 1  *  @li list 2  *  *  [내 블로그](http://onecellboy.tistory.com)  *  *        @code{.py}  *  #!/usr/bin/python  *        print "Hello World! 뜸금없는 파이썬 코드"  *  @endcode  *  *  이 클래스를 사용합니다. @ref Etc @n  *  이 네임스페이스의 이 클래스를 사용합니다. @ret subFolder.Etc  *  */ public function add($a,$b) { $sum = $a + $b;     return $sum; } }

 

 

출력 문서 전체

 

 

 

 

Doxygen 설치

$ sudo apt-get install doxygen doxygen-gui

 

 

Doxygen gui 실행

$ doxywizard

 

 

 

Doxygen GUI 설정

select : 소스의 위치를 지정 Pjorect name : 프로젝트 이름 Project viersion or id : 프로젝트 버전 Scan recursively : 소스 위치의 모든 하위 폴더까지 스캔(지정하지 않으면 하위폴더에 대한 문서는 생성 안함)

All Entities : 모든 엔트리 Include cross-referenced source code in the output : 각 함수마다 사용한 함수로의 링크를 생성   Select programming language to optimize the results for : 언어 지정

with navigation panel : 문서 왼쪽에 탐색 트리를 보여줌

Dot graphs to generate : 소스간의 관계를 GraphViz로 표현해줌

OUTPUT_LANGUAGE : 출력 문서 언어

ALWAYS_DETAILDE_SEC : 항상 상세 정보를 보여줌 INLINE_INHERITED_MEMB : 소멸자와 상속자를 제외한 상속된 모든 멤버를 보여줌

EXTRACT_ALL : 소스코드의 모든 요소가 문서화 대상이 됨 EXTRACT_PRIVATE : 클래스 내의 모든 private 멤버가 문서화 대상이 됨 EXTRACT_STATIC : 클래스 내의 모든 static 멤버가 문서화 대상이 됨

INLIVE_SOURCES : 함수 설명시 함수 코드를 보여줌

CLASS_DIAGRAMS : 클래스의 상속구조 다이어그램을 그림 UML_LOOK : 다이어그램을 UML 형식으로 그림

DOT_PATH : dot 프로그램(Graphviz)의 위치를 지정   Graphviz 설치법  sudo apt-get install graphviz 설치 위치 확인 : which dot

 

 

문서 만들기

Run doxygen 클릭   Show HTML output으로 문서 확인