Contents

개인적으로 외주개발일을 하면서 메뉴얼 및 구성요소에 대한 문서작업이 생각외로 벅차다는 사실을 알게 되었다. 주석분석툴을 찾던 중, ACE 메뉴얼을 만드는데 사용되는 Doxygen이란 툴을 접하게 되었다. 생각보다 강력한 툴에 문법도 간단하다. 설치에 대한 이야기를 먼저하도록 하겠다. (VC에 설치한 내용을 위주로 하도록 한다. 아마도 설치 메뉴얼을 거의 배끼지 않을까 생각된다. ^^)

1. Doxygen은 http://www.stack.nl/~dimitri/doxygen/index.html에서 구할 수 있다. 윈도우즈용 인스톨러가 있으므로 download 섹션에서 받으면 된다. 설치하기는 매우 쉽다.
   
   
2. 제대로 설치했으면 도스 프롬프트 상에서 Doxygen을 실행할 수 있다. 나중에 사용할 configuration 화일을 생성하기 위해 다음과 같이 실행한다.

   C:\> doxygen -g
   

   C 루트 디렉토리에 Doxyfile이란 화일이 생성된 것을 확인해본다.
   
   
3. graphviz를 받아서 설치한다. 이곳이 홈페이지이다. 클래스나 함수간의 관계를 이것을 사용해서 생성하는 기능이 있으므로 윈도우즈 배포판을 받아 설치해준다. 설치만 하면 된다. 이것은 클래스나 소스화일간의 관계를 그림으로 그려줄 때 사용한다.
   
   
4. 다음에는 Doxbar 차례다. 이것이 조금 골치아프므로 다음 단계를 따라서 한다. 우선 홈페이지에 가서 압축 배포본을 받는다. 알맞은 곳에 디렉토리를 만들고 압축을 푼다. (가급적 C 루트디렉토리와 가까운 곳에 만든다. doxygen관련 프로그램들은 너무 path가 길면 인식을 못하는 경향이 있다)
   
   
5. VC을 시작하고, Tools -> Customize... 메뉴를 선택한다. add-ins and Macro Files 탭을 선택한다. Browse버튼을 눌러 아까 압축을 풀었던 디렉토리로 가서 doxbar.dll을 선택한다. 이후에 open을 선택한다. 다음과 같이 설치되면 성공이다.
   
   
   
   
6. Close를 선택하고 빠져나오면 VC상의 다음과 같은 툴바가 생겨져있다.
   
   
   
   
7. 다시 Tools -> Customize... 메뉴를 선택한다. Tools 탭을 선택하고 새로 아이템을 추가한다. 그다음 다음과 같이 입력한다.
   
   
   
   위에서 rundox.bat화일은 실제로 존재하지 않지만 적어준다. Close를 선택하면 경고메세지가 뜰텐데, no를 선택해서 무시하자. (이 배치화일은 doxygen이 생성한다.)
   
   
8. Tools메뉴를 다시 선택해서 아래 그림과 같은 메뉴가 나타나면, doxygen이 몇번째 툴인지 기억해둔다. (그림에서는 7번째이다.)
   
   
   
   
9. (설정부분은 많이 개선되었지만, 제가 VC를 한동안 사용하지 않는 관계로 번역하지 않았습니다. doxbar 홈페이지의 설치그림을 참조하세요)
   
   
10. 마지막으로 Doxyfile을 고쳐보자. (doxygen은 한글을 지원한다. ^^) 다음 부분을 찾는다.

...
# The OUTPUT_LANGUAGE tag is used to specify the language in which all
# documentation generated by doxygen is written. Doxygen will use this
# information to generate all constant output in the proper language.
# The default language is English, other supported languages are:
# Brazilian, Chinese, Croatian, Czech, Danish, Dutch, Finnish, French,
# German, Greek, Hungarian, Italian, Japanese, Korean, Norwegian, Polish,
# Portuguese, Romanian, Russian, Slovak, Slovene, Spanish and Swedish.

OUTPUT_LANGUAGE        = English
...

우선 만만한 프로젝트화일을 열자. 프로젝트가 여러개 포함되어있는 경우라면 한개를 Active 시킨다. 툴바에서 맨 왼쪽 버튼을 눌러보자. 끝났다. 프로젝트가 담겨져 있는 디렉토리를 뒤져보면 html과 latex라는 디렉토리가 생겨있는 것을 볼 수 있다. html디렉토리안에 보면 도움말 화일(chm화일)과 html화일이 생성되어 있음을 볼 수 있다. 정말 간단하다! ^^;

doxygen은 소스를 몽땅 훑어 주석과 해당 코드를 파싱하여 메뉴얼을 생성한다. 자세한 사용법은 doxygen 홈페이지의 manual을 참조하기 바란다. (짬나는데로 이 부분을 정리해놓을 예정이다) 가장 간단한 사용법은 주석을 달때 !문자를 하나 더 붙이는 것이다. 즉, 다음과 같이 붙여보자.

...
//! 이것은 테스트용 함수다.
void func();
...

백문이 불여일run이다. ^^; 꼭 한번 자신의 나름대로의 게임용 라이브러리를 문서화해보길 바란다. 코딩과 다른 색다른 뿌듯함이 있다. ^^;

doxygen의 실행옵션을 변경하려면 설치단계중 2번째에서 생성한 화일의 내부를 고치면 된다. 다음과 같은 항목을 좋아하는 text 에디터로 수정하시길...

OUTPUT_LANGUAGE	결과물의 국적(!)을 나타낸다. Korean으로 맞추면 된다.
EXTRACT_ALL	생성후 비어있는 문서항목들도 모두 표시한다. YES로 맞추어주는 것이 좋다.
EXTRACT_PRIVATE	private 맴버들을 문서화할 것인지 여부.
EXTRACT_STATIC	static 맴버들을 문서화할 것인지 여부.
SOURCE_BROWSER	소스에 대한 직접적인 정보링크를 만들 것인지 여부. YES로 하는 것이 좋다.
HAVE_DOT	graphviz(설치단계에서 3번째)를 설치했다면 YES로 놓는다.

위 설치단계에서 2번 단계의 Doxyfile을 만만한 텍스트 에디터로 잘 수정하면 doxygen을 120% 활용할 수 있을 것이다. 개인적으로 많은 도움을 받은 툴이기에 이렇게 설치기를 적어본다. 이런 주석분석툴을 사용하면 코딩과 동시에 메뉴얼 작업을 같이 할 수 있는 장점이 생긴다. (자바에서는 javadoc이라는 것이 있다고 들었다.) 게임프로그래머라면 C/C++을 벗어나기는 힘드므로 이런 툴을 알아두면 팀원들끼리의 문서화와 작업교류, 프로젝트 도움말 작업 및 문서화 작업의 능률을 향상시킬 수 있으리라 믿는다.