Doxygen 사용법 (2) Detail version

1. Detail Version 에서 설명드릴 내용.

 

1) 개요

Simple Version에서는 Doxygen의 실행과 간단한 주석 추가에 의의를 두어 설명 드렸지만,

Detail Version 에서는 전체적인 설정 방법과, 자주 사용되는 주석의 사용법을 짚고 넘어 갈 예정입니다.

다만, Doxygen 을 사용하는데 있어서 반드시 필요한 내용은 아니니, 시간 나실 때 읽어보시는 것을 추천 드립니다.

 

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

DOXYGEN MANUAL_FILE.zip

 

 

2) 사전 준비사항

Doxygen 을 이용하는데 있어

Graphviz를 사용 하시는 것을 강력하게 권고 드립니다. 다운링크

Graphviz 를 사용하는 이유는.

전체 프로그램에 대한 정적 분석은 Doxygen 의 범위를 벗어나기에

Graphviz 를 사용해야 전체 프로그램의 Diagram 을 살펴보실 수 있기 때문입니다.

 

 

 

Graphviz를 사용하지 않는다면 클래스 구조는 아래 이미지와 같이 단순하게 나타납니다.

 

 

 

Graphviz 를 사용한다면 클래스 구조는 아래 이미지와 같이 상세하게 나타납니다.

단순히 상속 관계뿐만 아니라,

각 클래스 내에 어떤 행위를 포함하는지, 해당 행위의 캡슐화 상태가 어떠한지

변수 명, 변수의 캡슐화 상태 등 많은 정보를 한눈에 볼 수 있으며.

 

클래스 내의 함수 단위로도 서로 어떤 관계에 있는지,

함수간 호출 관계 그래프를 보여줍니다.

위와 같은 이유로

'개발자간’ 프레젠테이션 or 자료 공유 시 Graphviz 를 사용하는 것을 강력하게 권고 드립니다.

 

 

 

2.    Doxygen 프로그램 옵션 설명

 

Doxygen 프로그램의 옵션 별 세부 설명은 아래 이미지와 같습니다.

자주 쓰이는 옵션들만 기술 하였습니다. [기본적으로 세팅 파일이 포함되어 있으므로, 다 살펴보실 필요는 없습니다]

 

- Wizard (Project)

 

- Wizard (Mode)

 

 

- Wizard (Output)

 

- Wizard (Diagram)

 

- Expert (Project)

출력 언어 변경 시 위와 같이 한국어로 설명이 나타납니다. 

▶ 간혹 한국어로 출력시 Error 가 발생합니다. [Error : EUC KR to UTF-8 Failed.]

 

 

- Expert (Build)

 

- Expert (Input)

 

- Expert (Source Browser)

 

- Expert (Dot)

 

 

- SAVE 옵션

Doxygen 은 설정 내용을 프로그램 내부에 저장하지 않습니다,

추후 해당 설정을 다시 이용하려면 반드시 저장한 뒤, 해당 저장 파일을 보유하고 있어야 합니다.

 

Open 을 이용해 파일을 읽어오면 프로그램 상단에 불러온 설정파일의 경로가 표시됩니다.

▶  ./Doxygen_Setting 파일을 열어, Graphviz 의 경로만 잡아준 뒤 사용하시면 편리하게 이용할 수 있습니다.

 

 

 

3. 세부 주석 추가 방법

 

1) 간단한 주석 추가

☞ 다음 파일을 참고하시는걸 권장 드립니다

소스코드 - example1.html

문서화 파일 - Index.html

Simple Version 에서 위와 같이 간단하게 주석을 추가할 수 있다고 설명 드렸었습니다.

 

추가된 주석은 위와 같이 클래스와, 함수를 설명하는 부분에 설명이 명시되게 됩니다.

 

 

2) 상세한 주석 추가

☞ 다음 파일을 참고하시는걸 권장 드립니다

소스코드 – example2.html

문서화 파일 - Index.html

 

Doxygen 에서는 위와 같은 클래스, 함수에 관한 간단한 설명들 외에

문서의 메인 페이지를 수정하는 것이 가능합니다.

@mainpage	메인 페이지 문구
@section	개요 문구
@todo	할 일
@bug	버그
@ref	참고
@li	리스트
@code  “코드내용” @endcode	코딩
표 입니다 | A | B --------------------  수치     | 10 | 20 퍼센트   | 5  |10	표
@remark	주목할 내용

 

위 표에 나타난 옵션들을 이용하여서 .cpp 파일 내에 주석을 추가 해 보면,

 

메인 페이지 내에 위와 같이 나타낼 수 있습니다.

하위 메뉴에 위치한 ‘할일 목록’,’버그 목록’ 에는 메인 페이지에서도 볼 수 있는

@todo 목록과, @bug 목록이 나열되어 있습니다.

 

 

 

 

 

4.    Doxygen으로 복잡한 구조의 코드를 문서화 해 보자.

 

 

1) Doxygen으로 복잡한 구조의 코드를 문서화 해 보자.

지금부터 설명드릴 내용은

Open source Project 중 하나인 Chromium 프로젝트의 소스코드를 예시로 합니다.

 

Chromium Project 는 가장 유명한 브라우저인 Chrome의 뼈대가 되는 프로젝트로,

 

다들 아시다시피 Chrome 내에는 수많은 기능들이 포함되어 있습니다.

 

지금부터 만약의 상황을 가정하여,

당신이 촉박한 시간 내에 Chromium Project 의 소스코드를 분석해야 한다고 가정 해 봅시다.

엎친 데 덮친 격으로 제작자에게 다른 어떠한 설명도 듣지 못한 채, 소스코드와 클래스 별로 요약된 주석만을 전달받았고,

비 개발자 상대 프레젠테이션 자료 준비를 맡아, 클래스 내 세부구조의 Diagram까지 제작해야 한다고 가정 해 봅시다.

 

이와 같은 상황에서, 전체적인 소스코드의 맥락을 분석 하는데 만 하더라도 상당한 시간이 소요 될 것입니다.

비록 현재의 [Visual Studio 2022] 같은 IDE가 많이 발전했다 한들,

Chromium 과 같은 대규모 프로젝트의 세부 구조를 단시간 내 파악 하기란 어려울 수 밖에 없습니다.

구조를 파악한 뒤, Diagram을 그리는 작업 역시 시간을 상당히 소모하는 작업 입니다.

 

하지만 Doxygen 은 Chromium 프로젝트의 소스코드 프로젝트 폴더만 던져 주어도,

클래스 내의 특정 함수(ComputeGlobalNativeCodeResidentMemoryKb())의 호출 구조를 파악하고, 이를 Diagram

으로 나타내라는 요구를 완벽하게 수행 해 냅니다.

 

 

 

 

 

2) Doxygen 은 대규모 프로젝트도 문제없이 분석 해 낸다.

 

i7 9700K 기준, Windows Defender 동작으로 인해 리소스를 많이 뺏기긴 하였으나

Chromium 프로젝트 중 Services 폴더에 위치한 1300여개의 C++, h 파일을 분석 하는 데에 15여분 정도가 소요 되었습니다.

 

 

3) Doxygen 이 분석한 결과를 살펴보자.

Doxygen 을 돌려 보면 분석된 Chromium Project/Services 부분의 UML 을 살펴보실 수 있습니다.

 

 

 

 

5. Doxygen의 자잘한 팁

 

▶ 이상한 경로에 출력 파일이 생성된다

Step 1 경로를 다시 설정 해 보세요! (셋팅 파일로 실행 시 좀 이상한 반응을 보입니다)

 

▶ 한글이 깨집니다.

Input 옵션에서 [INPUT_ENCODING] 을 UTF-8 , EUC-KR로 서로 바꿔보시길 바랍니다.

깨지는 특정 조건이 있는 듯 한데 확인해 보지 못하였습니다.

 

 

이상입니다.