[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가 작성된 클래스와 메소드를 알수 있다. |
|
@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으로 문서 확인
|
