-
소스코드를 문서화 하는 툴 Doxygen안드로이드/소스&코드 2011. 3. 29. 16:20
▷ Doxygen 이란?
정해진 문법에 의해 쓰여진 C/C++/JAVA 등의 주석을 html/latex/pdf 형식으로 문서화 시켜주는 프로그램
▷ Doxygen 다운로드
http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
▷ 기본 설정
1. Doxygen 실행화면
2. Wizard를 실행시켜 필요한 정보를 입력한다.주의 : 프로젝트 경로에 한글명이 없어야 된다.
(예를 들어 C:/작업폴더/DoxyTest 로 경로가 주어질경우 Doxygen이 인식하지 못한다. )
하위 폴더가 있을 경우 Scan recursively를 체크할 것
해당 언어에 최적화 시킨다.( Doxygen이 자동으로 세부옵션을 설정해준다. )
필요한 문서 형태만 체크해둔다.
나열되어있는 diagram이 문서에 자동으로 생성되게 할 수 있다. 다만 GraphViz( http://www.graphviz.org/ ) 가 필요하며 문서 생성 속도가 매우 느려진다. 최종 완성 소스에서만 체크하는게 좋다. 3. Wizard로 기본적인 설정을 하고 Expert에서 세부적인 설정이 가능하다.
거의 손댈 부분이 없으나 취향에 따라 몇몇 부분을 고쳐주면 된다. OUTPUT_LANGUAGE 를 Korean 으로 바꾸면 메뉴가 한글로 나온다. 4. 설정한 Doxyfile 을 저장(Save)하고 Working directory 를 지정한 다음 Start 시키면 된다.▷ Doxygen 주석Doxygen은 파일, 함수, 데이터 구조를 기준으로 문서화를 한다. 코드 중간중간의 자잘한 주석은 문서화 시키지 않는다. 최종본의 형태는 JAVADOC(http://java.sun.com/j2se/1.5.0/docs/api/index.html )과 많이 유사하다.다음 예제에서 소스상의 doxygen 주석이 어떻게 doxygen 문서로 만들어지는지 알 수 있다./** \brief문자열 바꾸기
\remarks
입력된 문자열에서 원하는 문자열을 찾아 바꾼다.
\return
마지막으로 찾은 문자열의 첫번째 주소값을 반환한다.
*/
char *
Replace(
char * pStr, ///< 입력 문자열
char * find, ///< 찾을 문자열
char * replace ///< 변경할 문자열
)
{
...
}
위와 같이 코드에 주석을 단 다음에 Doxygen을 실행시켜 해당 소스를 돌려준다.
그러면 생성된 html 파일에서 아래처럼 보여진다.
\brief 나 \return 같이 doxygen에 기본적으로 지정되어 있는 keyword 이외에 다른 keyword를 사용하고 싶다면 \par 명령어를 사용하면 된다./** \brief
현재 시간을 얻는다.
\remarks
ST_TIME 구조체 형식으로 현재 시간을 얻는다.
\par 요구사항
time.h 선언이 필요하다.
\return
성공시 0을 반환한다. 에러가 발생하면 -1을 반환한다.
\author
이상호
*/
void
GetLocalTime(
ST_TIME * today
)
{
...
}
파일 기준으로만 함수나 변수가 나뉘어져 보이는데 임의의 그룹을 정해줄 수도 있다./**
\defgroup string 문자열 관련 함수
\defgroup date 날짜 관련 함수
*/
위와 같은 방식으로 그룹을 정의한 다음 해당 함수나 데이터 구조 코드의 위아래에 다음과 같은 코드를 삽입하면 된다./**
\addtogroup string
\{
*/
...
그룹화할 함수나 데이터 구조 코드
...
/** \} */
또한 메인페이지(MainPage)를 두어 프로그램의 전체 개요 등을 적어줄 수 있다.
Doxygen Documentaion(HTML) 의 Special Commands 섹션에서 Doxygen의 모든 명령어를 확인할 수 있다.첨부된 샘플코드는 소스파일 DoxyTest.c 와 메인페이지 MainPage.dox 로 이루어져 있다.▷ Doxygen 을 쓰게 되면 얻는 잇점역시 가장 큰 장점은 소스 코드 작성과 문서화가 동시에 이루어 진다는 점이다. 또한 소스 코드를 수정하더라도 문서화에 대한 부담이 적다.꼭 빠른 문서화가 목적이 아니더라도 Doxygen 주석을 쓰는 습관을 들이는 것은 여러가지 장점이 있다. 문서화 작업을 하면서 스스로 만든 함수를 한번 더 확인하게 되고 자잘한 버그부터 구조상의 문제점까지 발견하게 되기도 한다.댓글
