Jeonghun (James) Lee

2/11/2017

Ubuntu 에서 Doxygen 사용해보기

1. Doxygen 이란

doxygen은 오래전부터 존재하던 프로그램이며, 줄곧 사용해보고 싶은 프로그램이였다.
오래전에 다니던 회사가 이를 직접 이용하였고, 회사의 Code Convention 기반으로 소스의 API의 문서를 쉽게 구성하여 이를 배포하였다.

더불어 소스의 API 문서 뿐만아니라 이와 관련된 문서화 프로그램에 대해서 관심을 가지게 되었다.

기본 사용방법은 사용되어지는 프로그래밍 언어에 문서화가 필요한 API or Function에 각 회사에 맞는 Code Convention 주석으로

구현한 Function or API를 쉽게 문서화를 하는 것이다.

주석으로 문서화를 하기때문에 주석을 사용하는 방법만 알면 쉽게 적용하여, API 문서를 작성을 할 수 있다.
매번 open source를 사용할 때에도 Open Source의 doxygen을 이용하여 몇번 봐왔기에 궁금하였고, 어떻게 주석을 관리를 해야하는지 궁금하였다.

그리고 LaTex 역시 궁금한 문서화였으며, 이를 좀 더 자세히 알기 위해 간단히 정리하고자 한다.

LaTex란

https://ko.wikipedia.org/wiki/LaTeX

Doxygen 사용방법 Link

https://www.slideshare.net/arload/doxygen-33932243
http://onecellboy.tistory.com/342

상위 두사이트에 Code 와 주석을 어떻게 관리를 해야하는지 설명이 잘 되어있어, 본인도 한번 따라해보기 수준으로 관리를 해본다.

1.1 Ubuntu 에서 Doxygen 설치

Ubuntu 14.04 LTS에서 다음과 같이 doxygen을 설치해보자.

기본설치

 $ sudo apt-get install doxygen doxygen-gui

추가설치

 $ sudo apt-get install doxygen-latex doxygen-doc graphviz

Doxygen Build 및 설치
  https://www.stack.nl/~dimitri/doxygen/download.html#srcbin
  https://www.stack.nl/~dimitri/doxygen/manual/install.html#install_bin_unix

Doxygen 설치 및 사용법
  http://janghw.tistory.com/entry/doxygen-%EC%82%AC%EC%9A%A9%EB%B2%95

doxygen 실행

 $ doxygen --help

doxygen gui 실행

 $ doxywizard

doxywizard의 세부사용법

https://www.slideshare.net/arload/doxygen-33932243

1.2 Doxygen의 기본구성

Doxywizard : Front-end GUI program으로 Doxygen을 이용하여 문서화가 가능
Doxygen : Doxygen program으로, GUI가 지원이 안된다면 이것으로 실행

위에서 설명 했듯이 doxygen 의 기능은 code 안에 있는 주석을 parsing해서 이를 함수와 같이 문서화 하는 것이며,
이는 쉽게 문서관리를 하는 것이다. 이를 더 나아가 Makefile도 가능하며 이 기능역시 opensource에서는 많이 지원을 하고 있다.

예를들면 autoconf 파일에서 ./configure xxx --with-doxygen or --enable-doxygen
설정은 다양할 것이다. 이는 Makefile에도 영향을 미칠 것이며, m4 script도 같이 봐야 할 것이다.

보통 Output으로 많이 사용되는 것이 HTML/XML의 *.chm 와 *.pdf 방식이며, 개인적으로는 *.chm 방식이 검색 및 보기가 편하다.

doxygen 기본구조

https://www.stack.nl/~dimitri/doxygen/manual/starting.html

MarkDown 문법지원

쉽게 도식을 구성을 할 수 있으며, 요즘 Github에서 많이 사용되어진다.
https://www.stack.nl/~dimitri/doxygen/manual/markdown.html

Doxywizard 의 기본사용법

https://www.stack.nl/~dimitri/doxygen/manual/doxywizard_usage.html

주석의 구성예제

주석구성방법이며, 회사 Code Convention에 맞게 하도록하자.

/***********************************************************************************

* @fn      halJoystickIntConnect

*

* @brief   Connect isr for joystick move interrupt. The parameter event tells for

*          which joystick direction this isr should be called.

*

* @param   event - Joystick direction

*          func - Pointer to function to connect

*

* @return  none

*/

2. Doxygen의 Manual 및 Download

Doxygen을 사용할 경우, 알아야 할 기본 Manual과 Download하는 곳 과 이외 Tool들