How to use doxygen (MS 환경에서문서자동화 ) 2005 년 04 월 27 일 (Sunny Kwak) sunnykwak.egloos.com.
Copyrights 2005 Sunny Kwak, Inc. All rights reserved. Other disclaimers The names of actual companies and products mentioned herein may be the trademarks of their respective owners. Version History Version 1.0 (draft) 2005 년 4 월 25 일월요일 First created. 2 / 12
Table of Contents 1. INTRODUCTION...4 2. INSTALL...4 2.1 DOWNLOAD FILES... 4 2.1.1 Doxygen...4 2.1.2 Graphviz...4 2.1.3 Doxbar...4 2.1.4 html help compiler...4 2.2 INSTALL DOXYGEN... 5 2.3 INSTALL GRAPHVIZ... 5 2.4 INSTALL DOXBAR... 6 2.5 CONFIGURE DOXBAR... 6 3. RUN DOXYGEN...9 4. WRITE DOXYGEN STYLE COMMENT...9 3 / 12
1. Introduction Doxygen은주어진소스코드를분석하고소스코드에있는특정한형식의주석을이용해서소스코드를자동으로문서화해주는프로그램입니다. 결과는일련의 HTML 페이지혹은 LATEX나 PDF 문서들을만들어낼수도있습니다. 페이지들의기본적인내용은소스코드의클래스정의나함수정의등으로부터자동적으로생성됩니다. 클래스계통구조를보여주는도표 (gif 파일 ) 역시자동적으로생성됩니다. 그리고함수, 클래스등에대한텍스트설명은특정한형식을갖춘주석으로부터생성됩니다. 따라서 Doxygen의사용법을배운다는것은 Doxygen 프로그램의설정과실행에관련된것들을배우는것을의미할뿐만아니라 Doxygen이인식할수있는형태의주석을작성하는법을배운다는것을의미하기도합니다. 다행히 Doxygen 주석이일반적인방식보다특별히더복잡하지는않습니다. Doxygen 홈페이지 : http://www.doxygen.org/index.html http://www.codeproject.com/macro/kingstools.asp - Visual Studio.NET 에서 Doxygen 을사용할수있는툴 입니다..NET 을사용하시는분은이툴을사용해보시는것도좋을듯합니다. 2. Install 2.1 Download files 2.1.1 Doxygen http://www.doxygen.org/index.html 로가서 (Shift-클릭으로새창으로띄우세요 ~) source & binaries 페이지로가신후 Lastest release 아래 A binary distribution for windows 95/98/NT/2000/XP 라고되어있는부분의링크를클릭해서 zip 파일를받으세요.. 여기에는미리컴파일된이진실행파일들과매뉴얼 html 파일들이함께들어있습니다. 2.1.2 Graphviz 클래스간의관계를알아보기쉽게그림으로만들어내는기능을수행한다. 위에서다운로드받은파일 (graphviz-1.10.exe) 은윈도우용설치프로그램파일이다. 그대로실행시키 면디폴트값으로 "C:\Program Files\ATT\Graphviz" 경로에설치가된다. 2.1.3 Doxbar 비주얼스튜디오에서 Doxygen을편하게사용할수있게해주는 DoxBar라는것이있습니다. DoxBar 홈페이지 http://www.stack.nl/~dimitri/doxygen/doxbar/index.html 로가셔서 Binary라고되어있는 zip 파일을받으세요. VC++ add-in 입니다. 최신버전은 http://doxbar.sourceforge.net 에서구할수있습니다. 2.1.4 html help compiler HTML 도움말컴파일러이다. 다운로드받은파일 (htmlhelp.exe) 은윈도우용설치프로그램파일이다. 그대로실행시키면기본적으로 C:\Program Files\ HTML Help Workshop 경로에설치가된다. 4 / 12
2.2 Install doxygen 다운로드받은 doxygen-1.3.5-setup.exe 파일은윈도우용설치프로그램파일이다. 실행시킨뒤원하는 폴더에설치한다.( 디폴트값 : C:\Program Files\doxygen) * doxygen 이설치된경로아래의 bin 디렉토리에서다음과같은도스명령을실행시킨다. cd c:\program Files\doxygen\bin doxygen -g [ 템플릿파일명 ] 위도스명령에서템플릿파일명을지정하지않으면 Doxyfile 이라는이름의파일이생성된다. * 생성된템플릿파일을편집한다. 편집하기를추천하는부분은다음과같다. OUTPUT_LANGUAGE = Korean OUTPUT_LANGUAGE 의디폴트값은 English 로되어있는데 Korean 으로변경하면한글화된문서를 얻을수있다. EXTRACT_ALL = YES 생성후비어있는파일들도모두문서화한다. EXTRACT_PRIVATE = YES private 멤버들을문서화할것인지여부. EXTRACT_STATIC = YES static 멤버들을문서화할것인지여부 SOURCE_BROWSER = YES 소스에대한직접적인정보링크를만들것인지여부 HAVE_DOT = YES 다음에설명하게될클래스관계그림생성여부 (by graphviz) 2.3 Install graphviz 이프로그램은클래스간의관계를알아보기쉽게그림으로만들어내는기능을수행한다. 5 / 12
위에서다운로드받은파일 (graphviz-1.10.exe) 은윈도우용설치프로그램파일이다. 그대로실행시키 면디폴트값으로 "C:\Program Files\ATT\Graphviz" 경로에설치가된다. 2.4 Install Doxbar 이프로그램은 Visual Studio 6.0 에서 Doxygen 을사용하기쉽게해주는애드인프로그램이다. 다운로 드받은파일 (doxbar-0.35-bin.zip) 의압축을풀면다음과같은두개의파일을볼수있다. doxbar.chm doxbar.dll 위두개의파일을적당한디렉토리에복사한다. 예를들어 C:\Program Files\doxygen\Doxbar 디렉토리 를새로만들어서그안에집어넣는다. 2.5 Configure Doxbar 지금까지 doxygen, graphviz, doxbar 를모두설치완료하였다. 이제부터는 doxygen 을사용하여프로젝 트를문서화하기위한설정방법을알아보도록하겠다. Visual Studio 6.0 을실행시키고 Tools - Customize... 메뉴를선택한다. 6 / 12
그리고 Add-ins and Macro Files 탭을선택한뒤 Browse 버튼을눌러서 Doxbar.dll 을선택해주도록한다. Doxbar.dll 을등록시키면위그림에서와같이 Doxbar.DSAddIn.1 이추가된다. 이항목을선택하고 Close 버튼을누르면다음과같은툴바가 Visual Studio 에추가된다. 다시 Visual Studio 의 Tools - Customize 메뉴를선택하고 Tools 탭을선택한다. 7 / 12
위그림에나와있는것과같이 Doxygen 이라는항목을추가하고 Command 항목값으로 C:\Temp\rundoxy.bat 을등록한다. 여기에서등록한 rundoxy.bat 파일을실제로존재하지않는입력값이다. 따라서 Close 버튼을누르면실제로존재하지않으므로수정하겠느냐라는메시지박스가나타나는데아니오로선택하고종료하면된다. Doxbar 툴바버튼들중에서왼쪽에서두번째위치한버튼이 Doxygen 에대한환경설정기능을수행 한다. 환경설정을수행하기에앞서 Visual Studio 의 Tools 메뉴를선택하여방금전추가한 Doxygen 툴의번호가몇인지를확인하도록한다. Doxbar 툴바의두번째버튼을선택하면다음과같은환경설정대화상자가나타난다. 8 / 12
앞에서추가한 Doxygen 툴메뉴의번호대로 UserTool< 번호 > 를입력한다. 위그림에서는 Doxygen 이실행될때실시간으로만들어지는배치파일의경로, doxygen.exe 의경로, 디폴트템플릿파일의경로, HTML 도움말컴파일러의경로등을설정하고있는모습을보여주고 있다. 3. Run doxygen 이제마지막으로 doxygen 을실행시켜서프로젝트문서화를해볼차례이다. Doxbar 의맨왼쪽버튼을 누르면 Output 윈도우에주르륵표시되면서문서화가이루어진다. 4. Write doxygen style comment Doxygen 을이용한문서화는소스코드에있는주석에의존합니다. Doxygen 은소스코드를분석해서 9 / 12
클래스들이나그들의멤버들, 파일수준의함수나멤버들을조직화하고기본적인문서들을만들어 내지만, 각각의클래스나멤버, 함수, 구조체등에대한설명은주석으로부터비롯됩니다. Doxygen 이인식하는주석은이런형태입니다. /// 짧은설명 - JavaDoc 방식 /** 긴설명 - JavaDoc 방식... //! 짧은설명 - Doxygen 방식 긴주석 - Doxygen 방식... 이런주석들은정의나선언위에붙여야합니다. 예를들면 /// 어쩌구저쩌구클래스 class Foobar {... /// 이건생성자 /** 하는일 : 생성-.- Foobar() {...} 다음예제는 doxygen 의문서에있는예제입니다. Qt 스타일 //! A test class. ( 클래스에대한짧은설명 - 제목같은것이죠.) A more elaborate class description. ( 클래스의세부적인설명 - html tag도사용가능하다합니다.) class Test { public: //! An enum. ( 열거형에대한짧은설명 ) More detailed enum description. ( 열거형에대한상세한설명 ) 10 / 12
enum TEnum { TVal1, < Enum value TVal1. ( 열거형의값에대한세부설명 ) TVal2, < Enum value TVal2. TVal3 < Enum value TVal3. } //! Enum pointer. ( 멤버변수에대한짧은설명 ) Details. ( 멤버변수에대한세부설명 ) *enumptr, //! Enum variable. Details. enumvar; //! A constructor. ( 멤버함수에대한짧은설명 ) A more elaborate description of the constructor. ( 멤버함수에대한상세설명 ) Test(); //! A destructor. A more elaborate description of the destructor. ~Test(); //! A normal member taking two arguments and returning an integer value. \param a an integer argument. ( 함수파라메터설명 ) \param s a constant character pointer. \return The test results ( 함수의리턴값설명 ) \sa Test(), ~Test(), testmetoo() and publicvar() (See alse 같은참조를나타냄 ) int testme(int a,const char *s); //! A pure virtual member. \sa testme() \param c1 the first argument. \param c2 the second argument. virtual void testmetoo(char c1,char c2) = 0; //! A public variable. Details. int publicvar; 11 / 12
//! A function variable. Details. int (*handler)(int a,int b); }; 괄호안의내용을보면대충어떤식으로돌아가는지알수있을겁니다. javadoc 스타일을보면.. 마찬가지로 doxygen 에나오는예제를보지요. /** * a normal member taking two arguments and returning an integer value. * @param a an integer argument. * @param s a constant character pointer. * @see Test() * @see ~Test() * @see testmetoo() * @see publicvar() * @return The test results testme() 함수의주석부분입니다. 짧은설명은주석처음에 "." 으로끝나는부분까지해당합니다. 그리고다음에는세부적인설명이나오지요. 그런데 Qt스타일 (doxygen에사용되는스타일 ) param에 "" 를사용했는데, 자바스타일은 @ 를사용하는차이가있습니다. 자바스타일의 see는 Qt스타일의 sa 과동일합니다. 자바스타일로쓰실려면템플릿파일에 JAVADOC_AUTOBRIEF 옵션을 YES로해주시면됩니다. 12 / 12