[C, C++] Doxygen 설치와 작성 방법, Graphviz 설치까지

>> 비주얼스튜디오 주석 단축키

 

주석만 뽑아서 문서화 만들기, Doxygen

Doxygen은 소프트웨어 레퍼런스 문서 생성기입니다.
주석을 다는 목적은 코드에 관련된 기억을 쉽게 되살리고 남에게 코드에 대한 설명을 빠르게 전달하기 위해서입니다.

Doxygen을 사용하면 코드 버전에 따라 자동적으로 문서로 관리할 수 있습니다.
Doxygen의 주석 문법만 맞게 사용한다면 말입니다.

 

기본적인 Doxygen의 주석 형태는 다음과 같습니다.
@item들은 주석에 대한 메타데이터입니다.

/**
* 주석
*/

 

메인페이지 주석은 아래처럼 작성합니다.

/**
* @mainpage 메인페이지제목
* @brief 간략한 설명
* @details 자세한 설명
*/

 

파일 관련 주석은 다음처럼 작성합니다.

/**
* @file NewClass.java
* @brief 간략한 설명
* @details 자세한 설명
*/

 

클래스주석은 다음처럼 클래스 위에 작성합니다.

/**
* @brief 클래스 간략한 설명
* @details 자세한 설명
* @author lee
* @date 2021-11-09
* @version 0.0.1
*/

 

메서드 주석은 다음처럼 함수 위에 작성합니다.

/**
* @brief 간략한 설명
* @details 자세한 설명
* @param args 콘솔파라미터
* @return 프로그램 상태
*
* @bug 메모리 누수 있음
* @todo 해결 해야하는 버그
* @exception ...
*
* @see NewClass
* @see http:// ...
*/

 

 

더 자세한 item들에 대한 정보는 다음을 참고합니다.(이동)

Doxygen을 사용하려면 설치가 필요하며 함수 구조도, 클래스 구조도 등의 그래프를 문서에 포함시키기 위해 Graphviz 설치를 추천합니다.

 

 

Graphviz 설치 방법 (윈도우, 맥, 리눅스, Solaris 등)

https://graphviz.org/download/

Graphviz 설치

 

 

위 페이지에서 사양에 맞는 exe 설치 파일을 다운받아 실행합니다.
동의함을 선택하고 Add Graphviz to the system PATH for current user를 선택합니다. 

 

 

 

이러면 사용자변수 PATH를 지정할 필요가 없어 편하지만, 기본값으로 해도 나중에 별도로 지정할 수 있습니다.
설치할 폴더 경로를 선택한 후 다음을 클릭합니다. 바로가기 아이콘 여부를 선택하고 설치를 누르면 완료됩니다.

 

 

Doxygen 맥 설치 방법

터미널에 다음을 입력합니다.
Doxygen 패키지와 graphviz를 한꺼번에 설치하는 문장입니다.

sudo apt-get install doxygen graphviz

 

 

Doxygen 윈도우 설치 방법

https://www.doxygen.nl/download.html

Doxygen 윈도우 설치, 설정 방법

 

Doxygen 을 윈도우에 설치하면서 설치 과정을 캡쳐해 남겨 보았습니다.
Doxygen 설치 과정 중엔 특별히 할 것이 없습니다.

 

 

 

Doxygen 을 설치한 후 프로그램을 실행시켜 설정을 해 주어야 할 것들 몇 가지가 있습니다.

1) 프로젝트 루트 폴더 지정
2) 소스파일 폴더 지정
3) Scan recursively 체크박스에 체크
4) Destination directory 폴더 지정 (Doxygen이 문서를 생성할 폴더)
5) 프로젝트의 이름과 버전 지정

 

 

Doxygen 루트 설정

 

 

6) 각 함수마다 사용한 함수로의 링크 생성 체크
7) 해당 언어 선택

 

 

 

8) 문서 왼쪽에 탐색 트리 보이기 체크
9) 소스 간의 관계를 GraphViz로 표현할 것 체크

 

 

 

 

10) OUTPUT_LANGUAGE 체크 (출력 결과에 쓰여질 언어)
11) ALWAYS_DETAILED_SEC 체크 (항상 상세 정보 출력)
12) INLINE_INHERITED_MEMS 체크 

 

 

 

 

13) EXTRACT_ALL(소스코드의 모든 요소가 문서화 대상으로)
14) EXTRACT_PRIVATE,  EXTRACT_STATIC (체크 클래스 내 private, static 멤버 포함할 지)
15) INLINE_SOURCES 체크 (함수 설명 시 함수 코드 보임)

 

 

 

 

16) CLASS_DIAGRAMS 체크 (상속구조 다이어그램 그림)
17) UML_LOOK 체크 (다이어그램을 UML 형식으로 그림)
18) DOT_PATH (Graphviz를 의미)

 

 

Run doxygen 버튼을 눌러 문서를 생성시킨 후 , Show HTML output를 통해 생성된 문서를 조회할 수 있습니다.

 

 

the dot tool could not be found at 오류

원인 : OUTPUT_DIRECTORY가 C로 되어있어서 write가 안되서 그런 것 같습니다
그리고 그 전에 났던 오류 : OUTPUT_LANGUAGE가 Korean일 경우. Korean-en으로 바꾸니 문제없습니다.

 

 

 

참고

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