공동 혹은 협력 개발 작업을 하다가 보면 서로의 정보를 공유하기 위해
매우 다양한 방법을 사용하게 됩니다.

그러한 방법 중에 하나로 서로가 개발한 부분의 사용법이나
자세한 작동 내용을 설명하기 위해 클래스나 함수들의 용법을 설명하는
문서를 자주 사용하게 됩니다.

그런데 이러한 문서를 작성하고 있다보면
개발보다 결코 쉽지 않고 만만치 않은 시간이 소비됩니다.
이미 개발하는 당사자도 많은 주석을 통해 코드 곳곳에 정보를 남겼을 것인데
이를 다시 보기 좋게 정리하고 문서에 투자하는 시간은 어쩌면 낭비되는 시간일지도 모릅니다.

이러한 고민이 아주 오래전부터 있었던 모양입니다.
벌써 많은 문서화 툴이 제작되고 사용되고 있는 중이지요.

이 글에서는 그중에 비교적 빨리 적응할 수 있고
오픈 소스 정신에 입각하여 누구나 사용할 수 있는 Doxygen을 소개하고자 합니다.

역시나 많은 분들이 사용하는 Windows XP 이상을 기반으로 설명할 것이며
DoxyWizard를 사용하는 것을 주로 설명합니다.

1. 설치
    관련 주소 : http://www.stack.nl/~dimitri/doxygen/ - 개발자의 홈페이지
 우선 다운로드 주소에서 윈도우즈용 최신 버전을 다운로드해서 설치합니다.
 그리고 그래프를 표현하기 위한 프로그램인 Graphviz도 다운로드해서 설치합니다.

2. 테스트용 소스
 다음과 같이 테스트용 소스를 만들었습니다.
 Doxygen은 다양한 형식의 주석을 지원합니다만 아래의 테스트 코드는 제가 흔히 사용하는 스타일로 적어 보았습니다. Doxygen의 문법은 KLDPWiki를 참고하시면 좋습니다.

소스 보기

※ 주의사항 : 한글을 혼용하기 위해서 UTF-8로 소스를 작성하시는 것이 좋습니다. 그리고 UTF-8로 비주얼 스튜디오에서 작업하실 때 파일 첫부분에 빈공백을 넣어주어야 정상적으로 작동하는 것을 확인했습니다.

VS2005의 UTF-8 저장하는 법

3. 문서 생성 - Step1
 자 위의 소스가 작동하는지 안하는지는 머리 아프게 고민하지 말고 바로 문서를 만들어 보도록 하겠습니다. 우선 DoxyWizard를 실행합니다.
  Wizard 버튼을 눌러서 몇가지 설정을 따라합니다.

Wizard 설정

OK 버튼을 누르고 나면 대다수 설정을 마쳤습니다. 추가로 몇가지 설정을 더 살펴보고 문서를 생성하도록 하겠습니다.

 Expert 버튼을 눌러서 고급 설정으로 들어갑니다.

Expert 설정

OK 버튼을 눌러서 설정을 적용합니다.
소개된 것 외에도 많은 옵션이 있으므로 Doxygen 문서를 확인하시면서 이것저것 시도해서 확인해 보시는 것도 좋습니다.

4. 문서 생성 - Step2
 우선 설정 파일을 저장해야 합니다. doc 디렉토리를 만들고 Save 버튼을 눌러서 그곳에 저장하겠습니다.
그러면 상태가 '저장됨'으로 바뀝니다.
저장하지 않으면 문서를 생성할 수 없을 뿐더러 아무 경고 없이 이제까지 한 설정이 날아갈 수도 있습니다. 물론 한번 저장해둔 설정은 Load 버튼으로 언제든지 다시 불러서 계속 생성할 수 있습니다.

5. 문서 생성 - Step3
 Doxygen이 작업할 디렉토리를 선택합니다. 로그 파일이나 생성 중의 중간 파일 등이 사용할 위치입니다. 그냥 doc 디렉토리를 선택하겠습니다.

6. 문서 생성 - Step4
 Start 버튼을 눌러서 최종적인 문서를 생성합니다. 만약 오류가 있었다면 로그창에 표시됩니다. 그러면 해당 오류 부분을 바로잡아 주고 다시 생성하면 됩니다. 소스 코드에는 어떠한 위해도 가하지 않으므로 Doxygen의 오류 코드를 심각하게 걱정할 필요는 없습니다. 제 경험상으로는 GraphViz와의 오류가 많았습니다만 한번 작동하는 옵션 조합을 발견하고 나면 문제없이 잘 작동했습니다. SHORT_NAMES라는 옵션을 한번 확인해 보시기 바랍니다.

7. 문서 확인
 바야흐로 생성된 문서의 결과를 확인할 때가 되었습니다. 작업 디렉토리로 선택했던 doc 디렉토리를 보면 html이라는 디렉토리가 생성되었을 것입니다. 이 디렉토리 안의 index.html을 열어서 확인해 보겠습니다.
클래스 계통도까지 삽입되어서 매우 깔금한 문서가 만들어 졌습니다. (그런데 프로젝트 제목의 한글 부분은 손상되었군요. 프로젝트 제목은 한글로 입력하면 안되겠습니다.)

그리고 VERBATIM_HEADERS 옵션을 사용했기 때문에 헤더 파일의 전체 코드가 포함되었습니다.
DoxyWizard의 사용법을 중심으로 Doxygen 사용법을 알아보았습니다.
많은 분들이 Doxygen을 사용하여 문서화의 작업 시간을 단축하셨으면 하는 바램입니다.

크리에이티브 커먼즈 라이선스

이 저작물은 크리에이티브 커먼즈 코리아 저작자표시-비영리-동일조건변경허락 2.0 대한민국 라이선스에 따라 이용하실 수 있습니다.