Doxygen을 활용하여 코드 문서화

  글쓰기는 쉽지 않습니다.

특히 개발자에게 글쓰기는 왠지 하지 않아도 되는 일을 하는 듯한 느낌마저 듭니다.

하지만 글쓰기는 경력이 더해질수록 점점 중요해진다는 것을 염두해 두세요.

이번 글에서는 보고서나 PPT의 글쓰기가 아닌 코드 문서화에 대해 이야기하려고 합니다.

며칠 전에 H사에서 저희들이 납품한 프로그램에 대해서 자체적으로 유지 보수를 하려고 코드 설명서를 보내달라고 요청이 왔습니다.

일반적으로 고객사는 프로그램 설명서는 요청하지만 코드 설명서는 요청하지 않습니다.

아마 자체적으로 프로그램을 유지 보수 하려다 보니 소스에 대한 설명이 필요해서 코드 설명서를 요청한 것으로 보입니다.

MSDN과 같은 훌륭한 설명서를 작성하기에는 저희들은 인적,물적 그리고 시간적으로도 여유가 없습니다.

그래도 개발자가 일주일이라는 시간을 투입하여 문서를 작성한 후에 고객사에 전달하였습니다.

이 문서가 소스 파악에 얼마나 도움이 될지는 저로서는 미지수입니다.

얼마나 도움이 될지도 모를 문서를 작성하는데 들어간 일주일이라는 시간이 아깝게 느껴집니다.

코드 설명서는 코드에서 충분히 만들 수 있고 그리고 Doxygen이라는 훌륭한 툴이 있습니다.

Doxygen에 대한 설명은 여기서 확인할 수 있습니다.

Doxygen에서 제대로 코드 설명서를 생성하기 위해서는 Doxygen이 인식할 수 있는 형식으로 주석을 달아줘야 합니다.

Doxygen 주석 형식은 여기서 확인하시면 됩니다.

Doxygen은 여기서 다운 받아 설치하면 됩니다.

Doxygen을 사용하기 위해서는 우선 환경 설정을 해야 합니다.

환경 설정의 내용은 Doxyfile이라는 파일로 저장됩니다.

Doxyfile은 텍스트 파일로 직접 수정할 수도 있고 Doxygen GUI를 통해 수정할 수도 있습니다. 

Doxygen GUI 화면

자세한 환경 설정은 여기서 확인하시면 됩니다.

이렇게 생성한 코드 설명서를 로컬에만 둔다면 활용성이 떨어집니다.

코드 설명서를 위한 사이트를 만들어 거기에 올리는 것이 여러 사람들이 볼 수 있어 문서의 활용성이 높아집니다.

많은 Opensource 프로젝트에서도 코드에 대한 문서를 웹으로 제공하고 있습니다.

코드 문서화를 위한 웹 사이트 구축을 간단히 하기 위해 웹 사이트가 구축된 머신에서 Doxygen을 실행하여 문서를 생성하도록 합니다.

사이트를 구축한 후에 Doxygen의 출력 폴더를 사이트의 하위 폴더로 설정합니다.

IIS에 코드 문서화 관련 사이트 생성

$$OUTPUT\text{_}DIRECTORY\text{ }=\text{C:\inetpub\wwwroot\Doxygen\Sample\\}$$

이제 Doxygen에서 문서를 생성하면 해당 경로에 파일이 저장되어 웹에서 확인할 수 있습니다.

출력 폴더 접근 권한 문제로 문서가 생성되지 않을때 User에 읽기/쓰기 권한을 부여하면 됩니다.

이러한 일련의 작업을 Jenkins를 통하여 자동화시켜 놓으면 클릭 한번으로 코드 설명서를 작성하고 웹에서 확인할 수 있습니다.

Jenkins의 Global Tool Configuration에서 Windows Exec에서 Doxygen 명령어를 등록합니다.

Doxygen 명령어 등록

Jenkins의 Build 스텝에서 Windows Exec로 Doxygen 명령어를 등록합니다.

Command Line Arguments에는 비워둬도 됩니다.

소스의 Root 폴더에 있는 Doxyfile을 이용하여 문서가 작성됩니다.(Doxyfile을 소스 관리 시스템을 이용하여 관리하는 것이 좋습니다.)

Jenkins를 이용하여 프로젝트를 빌드할때마다 코드 문서가 생성됩니다. 

코드 문서화 화면