소스코드 문서화 도구, Doxygen..

개인적으로 만들고 있는 프로그램이 있는데, 시간이 날때만 조금씩 띄엄띄엄 작업을 하다보니 가끔은 저 자신도 어디서부터 다시 손을 봐야 할지 감을 찾는데 시간이 오래 걸리는 경우가 있습니다. 소스에 주석을 달아놓기는 하지만 라이브러리의 전체적인 윤곽을 빨리 훑어보는데에는 주석만으로는 좀 부족하죠. 그래서 소스코드 문서화 도구를 이용해 보기로 마음을 먹었습니다.

아무래도 가장 많은 사람들이 사용하는 도구가 일반적인 용도로는 가장 유용할 가능성이 높다고 할 수 있죠. 가장 유명한 Doxygen을 써보기로 했습니다.

(링크) Doxygen, Source code documentation generator tool

이 글을 작성하는 시점에서 최신 버전은 1.5.2입니다만, 설치해서 테스트해보니 한글로 작성한 주석을 제대로 처리하지 못합니다. 관련된 내용을 좀 찾아보니 1.5.2는 자체적으로 문자열 인코딩/디코딩 기능을 구현한듯 하고, 직전 버전인 1.5.1-p1은 OS의 인코딩을 따라가는듯 합니다. 자체 기능이 제대로 구현될 때까지는 OS를 따라가는 1.5.1-p1을 쓰는게 정신건강에 좋을듯.

(링크) Doxygen 1.5.1-p1

설치해보니 한글 주석이 잘 처리됩니다. 문서 생성 설정을 찾아보니 클래스간의 관계를 그래프로 그려주는 기능이 있는데, 이걸 활용하려면 dot라는 도구가 필요하다고 합니다. dot는 Graphviz에 포함된 그래프 생성 도구라네요.

(링크) Graphviz - Graph Visualization Software

Windows용은 다음 링크에서 받을 수 있습니다.

(링크) Graphviz Download (Windows)

필요한 도구를 모두 설치하고 옵션을 설정하여 문서를 생성해보니 클래스 및 멤버 목록과 관계도, 색인 등이 포함된 꽤 괜찮은 문서가 나오긴 하지만 정작 제가 작성해 놓은 주석은 포함되지 않는군요. C++의 경우에는 Doxygen이 인식할 수 있도록 주석 스타일을 바꿔서 달아줘야 생성된 문서에 주석이 포함된다고 하는데, 앞으로 작성하는 주석부터 그렇게 하기로 하고 이전 주석을 수정하는 노가다는 하지 않기로 했습니다. 조금씩 코드를 수정하다보면 언젠가는 전부 Doxygen 스타일로 바뀔 날이 오겠죠.

시험삼아 C# 프로젝트를 하나 문서화해 보았는데, 이 쪽은 결과가 훨씬 좋습니다. Visual Studio .NET 개발툴이 C#에 대해서는 어느정도 주석의 스타일을 강제하는데,(인텔리센스-자동표시기능-에 주석이 표시될 수 있도록 하기 위해서 그렇게 하는듯) 이를 정확히 인식하기 때문에 생성된 문서에 필요한 주석이 고스란히 포함됩니다. Doxygen을 대비해서 주석을 신경써서 달지 않은 경우에는 C++보다 C#쪽 프로젝트를 Doxygen으로 문서화하는게 더 효율적일것 같네요.