Doxygen 사용법 (1) Simple version

1.    Doxygen 이란

소스코드에 대한 설명을, 간단하게 생성할 수 있게 해 주는 프로그램 입니다.

이 설명의 범주에는 다음과 같은 것이 포함됩니다.

 

1) 클래스 별 관계도

 

2) 클래스, 함수에 대한 개요

 

3) 클래스, 함수에 대한 개발자의 설명

 

 

 

 

 

2.    Doxygen 의 설치

Doxygen 은 Doxygen 그 단독으로만 사용해도 충분히 유용하나,

다른 프로그램과 융합하여 사용한다면 보다 높은 효율로 사용할 수 있습니다.

 

Doxygen 의 설치는

Doxygen 사이트 내에서 운영체제 별로 선택하여 설치하면 됩니다.

 

더하여 위에서 언급한 관계도 등을 UML로 자세히 표현하고 싶다면

graphviz역시 설치하면 됩니다.

 

추가하여, Doxygen 과 타 프로그램을 융합하면, 출력파일을 바꾸는 것이 가능합니다.

LaTeX 를 이용해 LaTex 문서로 생성 하거나,

PDF 파일로 출력하는 것 역시 가능합니다.

 

▶ simple version 기준에선 Doxygen 만 설치하셔도 됩니다.

▶ Doxygen 설치 경로에 한글 포함 시 에러가 발생한다는 보고가 있습니다.

 

 

 

 

 

3.    Doxygen 의 장, 단점

 

장점

1) 문서가 필요 없어진다.

소스코드 내에 설명을 주석으로 추가할 수 있으므로,

word, hwp 등에 소스코드 설명을 분리하여 기술할 필요가 없어집니다.

따라서 설명문서를 작성하고 / 관리하는데 소요되는 시간을 단축할 수 있습니다.

 

2) UML 을 자동으로 만들어 준다.

개발자 상호간 소통의 향상 뿐 아니라,

비 개발자의 프로그램 구성 이해를 위한 UML을 자동으로 제작할 수 있어

자료 제작에 소요되는 시간을 대폭 감축할 수 있습니다.

 

3) HTML, PDF 등 브라우저 표준만으로 볼 수 있는 형식을 지원한다.

배포 시에 HWP, Word 와 같이 프로그램 이나, 운영체제에 따른 의존성을 걱정하지 않아도 됩니다.

 

단점

1) 가독성 저하, 소스파일 용량 증가 문제 발생.
소스코드 자체에 Doxygen 용 주석을 추가해야 하므로,
가독성 저하 문제와, 소스코드가 길어지는 문제를 발생시킬 수 있습니다.

 

 

4.    Doxygen 실행과 사용

☞ 아래 파일을 다운로드 하셔서 참고하시는걸 권장 드립니다

DOXYGEN MANUAL_FILE.zip

소스코드 - example1.html

문서화 파일 - Index.html

 

1)     Doxygen 설치하면 doxywizard 실행 파일이 만들어 집니다.  |  (Linux 명령 doxywizard)

-       Step 1
Doxygen 결과 파일을 저장할 경로를 입력하는 란 입니다.

-       Project Name
Doxygen 결과 파일의 title로 사용되는 이름입니다.

-       Source code directory
CPP, H 파일이 위치한 폴더 경로를 설정 해 주어야 합니다.

-       Destination directory
지정하지 않을시 → [Step1 에 지정한 폴더 / html / index.html]
지정 할 시      → [Step1 에 지정한 폴더 / Destination dirtectory / html / index.html

 

2)     Wizard-Mode 옵션 선택 후 프로그래밍 언어를 선택 합니다.

 

 

3)     Run 카테고리서, Run doxygen 버튼을 눌러줍니다.

 

 

4)     생성된 Doxygen 관련 파일을 확인합니다

 

 

Step 1에 설정한 경로에 다음과 같은 두 가지 폴더가 만들어 집니다.

Html 폴더를 열어 Index.html을 확인해 보면 전체적인 구조를 확인하는 것이 가능합니다.

▶ 위 창에서 show HTML output 버튼을 눌러 확인하는 것 역시 가능합니다.

 

 

 

 

5)     Index.html 파일 확인

-       Index.html 파일을 연 후, Class List 를 확인해 봅니다.

-       Class List 에서는 다음과 같이 생성된 class 를 확인하는 것이 가능합니다.

 

-       Animal Class를 클릭해 들어가면

(1)    해당 클래스의 종속 관계

(2)    클래스에 대한 설명

(3)    메소드에 대한 설명

(4)    개발자가 제공하는 추가적인 설명을 확인할 수 있습니다.

 

 

 

 

 

 

5.    Simple Version 주석 작성법

Example1.cpp or example1.html 를 확인해 보면 다음과 같은 주석문이 보입니다.

 

위와 같이 나타나게 됩니다.

여기서 임의로 넣은 @frog 문구는 적용이 되지 않은 점을 보아.

반드시 ‘예약어’ 를 이용해야 한다는 점을 알 수 있습니다.

            

Class 의 대한 주석 ‘예약어’는 다음과 같습니다.

@brief	간략한 설명
@detail	자세한 설명
@author	저작권자
@data	날짜
@version	버전정보

 

Method 에 대한 주석 ‘예약어’는 다음과 같습니다.

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

          

▶ class | Method 주석에 대한 예약어는 서로 호환됩니다, 즉 @param 문을 class 주석 에서도 사용이 가능합니다.

 

 

 

 

6.   마치며

Doxygen 에 관한 가장 기본적인 작업을 Simple Version 에 기술 하였습니다.

여기까지만 알아두고 사용해도 기존 대비해, 개발 외적으로 소요되는 시간을 대폭 단축할 수 있을 것이라 생각 됩니다.

Detail Version 에서는 Doxygen 의 세부적인 사용법에 대해 자세히 기술 하겠습니다.