프로그램 소스로 문서를 만들어 주는 Doxygen

2009.04.21 17:39 컴퓨터/유틸리티
Doxygen을 사용한지 얼마 않되지 정말 좋네요. 문서 작업 하는 것을 좋아 하실 분이 과연 계실까요? 프로그램 작성도 힘든데, 일을 끝내도 만들어진 프로그램을 가지고 문서 작업을 하려면 한숨부터 나옵니다. 더욱이 프로그램을 수정할 때마다 문서도 함께 변경하려면, 정말 보통 일이 아니죠. 그래서 한참 열심히 Doxygen을 학습하고 있는데, 이 글에서는 지금까지 제가 알고 있는 지식을 정리하고, 더 자세한 내용은 Falinux Forum에 연제로 올리고 있습니다. 관심 있는 분은 참고 하세요.

우선 설치부터 해야겠지요. Doxygen은 글로만 문서를 작성하지 않습니다. 함수의 관계를 보기 좋게 그래프로 작성하여 문서에 넣어 주는데, Doxygen이 이런 그래프를 만들기 위해서는 “Graphviz - Graph Visualization Software”의 graphviz-2.22.2.msi를 설치해 주어야 합니다.

 

Doxygen 설치

  1. Graphviz - Graph Visualization Software”의 graphviz-2.22.2.msi를 설치
  2. Doxygen 1.5.7 설치

graphviz-2.22.2.msi를 설치하실 때는, 사용 대상을 반드시 "Everyone"을 선택하십시오. 저 같은 경우 “Just me”를 선택하면 제대로 설치가 안 되더라구요. 이유는? 모르겠습니다. ^^;

이 글을 작성하고 있는 지금, Doxygen 가장 최근 버전은 1.5.8인데, 제 PC에는 설치가 안 되서 1.5.7을 사용하고 있습니다.

Doxygen 실행

Doxygen을 맛보기 하려면 대상 소스가 있어야겠지요. 이해를 돕고자 샘플 소스를 첨부합니다.

Doxygen을 알고부터 저의 프로젝트 디렉토리 구성이 바뀌었습니다. 예전에는 프로젝트 디렉토리 바로 밑에 프로그램 소스 파일을 바로 작성했는데, 지금을 “source” 디렉토리를 만들어 놓고 모든 프로그램 소스를 이 디렉토리 안에 모아 작성합니다. 그리고 “Doxygen” 디렉토리를 만들어서 모든 Doxygen 작업을 이 디렉토리에서 모두 합니다. 즉, 아래와 같은 구성이죠.

 

[Wizard...] 버튼

Doxygen을 실행합니다. 제일 처음 [Wizard...] 버튼을 클릭합니다.

doxywizard 대화상자에서 “Project” 탭입니다.

순서에 따라 적당한 값을 지정해 주시면 됩니다.

  1. Project name 프로젝트 이름을 넣어 주십시오.
  2. Project verion or id 프로젝트 버전이나 다른 프로젝트와 구별할 수 있는 식별 번호를 입력합니다. 정해진 형식은 없습니다. 자유롭게 입력하십시오.
  3. Source code directory 소스 파일이 있는 디렉토리를 지정해 줍니다.
  4. Scan recursively 소스 파일이 소스 디렉토리 안에 또 다른 디렉토리 안에 작성되어 있다면, 모든 하위 디렉토리까지 뒤져가면서 문서를 작성할지의 여부를 지정합니다.
  5. Destinatione diectory Doxygen이 문서를 어디에 생성할지를 정해 주는데, 자동으로 “html”디렉토리를 생성하므로 Doxygen을 위한 디렉토리를 지정해 주면 됩니다.

다음은 doxywizard 대화상자에서 “Mode” 탭입니다.

 

  1. Include cross-refeenced source code in the output 이 옵션을 체크하면 각 함수마다 사용한 함수 코드로 바로 Jump할 수 있는 링크를 생성해 줍니다. 즉, 이 옵션을 끄고 문서를 만들면 아래와 값이 됩니다.



    그러나 옵션을 체크하고 문서를 생성하면 호출된 함수로 이동할 수 있는 링크가 생성됩니다.



    그래서 이 링크를 클릭하면 해당 함수의 소스 코드로 Jump합니다.


    괜찮죠? ^^
  2. C 프로그램 소스라서 “Optimize for C output”을 선택했습니다.

이번에는 doxywizard 대화상자에서 “Output” 탭입니다.

 

  1. HTML 어떤 파일로 만들지를 선택하는 항목인데, 저는 HTML 형식만 체크했습니다.
  2. with frames and a navigation tree 또한 문서 왼쪽에 탐색 트리가 있는 것이 편하므로 “with frames and a navigation tree”를 체크했습니다.

마지막으로 doxywizard의 “Diagrams” 탭입니다. Doxygen에서 소스간의 관계를 그래프로 출력해 주는 기능이 있는데, 이를 Dot Tool 이라고 하더군요. 당연히 이 관계 그래프가 출력되는 것이 좋으므로 모든 옵션을 체크했습니다.

이제 [OK] 버튼을 클릭하여 작업을 완료합니다.

[Expert...] 버튼

Doxygen 에서 [Expert...] 버튼을 클릭합니다.

[Wizard...]버튼보다 더 많은 탭들이 출력되는데, 저는 아래와 같이 옵션을 선택하여 사용합니다. “Project” 탭입니다.

 

  1. DOXYFILE_ENCODING 한글 문제를 피하기 위해 “EUC-KR”로 변경합니다.
  2. OUTPUT_LANGUAGE 탐색 트리에서 한글이 깨지는 것을 피하기 위해 “English”를 선택합니다.

Input” 탭입니다.

 

  1. INPUT_ENCODING 한글이 깨지는 것을 막기 위해 “EUC-KR”로 변경합니다.

Source Browser” 탭입니다.

 

  1. INLINE_SOURCES 함수 설명에서 함수 코드가 들어 가도록 “INLINE_SOURCES”를 체크했습니다.

[Save]와 [Select] 버튼

[Save] 버튼을 이용하여 지금까지 변경했던 옵션 내용을 파일로 저장합니다. 또한 [Select]버튼을 이용하여 Doxygen이 작업하는데 사용하는 디렉토리를 선택해 주셔야 하는데, c:\temp 같은 임시 디렉토리를 선택해 주면 됩니다.

 

[Start] 버튼으로 문서 만들기

이제 모든 설정 작업이 완료되었습니다. [Start]버튼으로 문서를 생성하면됩니다. 큰 문제가 없다면 아래와 같이 “Destinatione diectory”로 지정한 디렉토리 밑에 “html” 디렉토리가 생성되고 그 안에 html 파일이 생성됩니다.

생성된 파일을 열어 보시면 Doxygen이 고생한 결과물을 보실 수 있습니다.

만들어진 문서를 보면 꽤 괜찮다는 거을 아실 수 있을 것입니다. Doxygen을 생각하면서 주석문을 조금만 더 충실히 달아 두면 나중에 큰 도움을 받을 수 있으리라 생각됩니다.

이 댓글을 비밀 댓글로
  1. 예전에 한두번 써보고는 최근에는 안써봤는데 다시 시도해봐야겠군요.

    그리고, 캡쳐화면에 화살표는 어떻게 넣으시나요?
    저도 가끔 캡쳐해서 설명할때 오픈캡쳐 툴에서 지원하는도구로 빨간 박스치거든요.
  2. 이런 아름다운 프로그램이 있을 줄이야..;;

    다행이 리눅스용, 맥용도있네요 .. 아직 이런게 할만한 이렇다할 큰 프로그램은 만들어 본적은 없지만..
    상당히 흥미롭습니다.. 전에 프리젠테이션 하느라고 그거 일일이 그린거 생각하면 눈물이 앞을 가리는군요..
    • kaze
    • 2009.04.22 08:31
    저두 써봤는데 생각보다 좋은 프로그램이더군요..
    물론 주석다는게 일이지만. 깔끔하고, 다른사람한테 프로그램 이관할때도 편할것 같더라구요...

    회사 때려칠때 던져주고 나가면 될듯.. ㅋㅋ
    • 업무 인수인계 때에도 좋지만 나중에 프로그램을 다시 이효하는데에도
      도움을 받았으면 좋겠습니다.
      제가 작성한 프로그램도 시간이 지나면 헤깔려서 말이죠. ^^
    • 스카
    • 2009.04.22 20:28
    #### 안녕하세요. 길석님...


    프라다폰 2 작업때문에 한참 정신없었습니다..^^

    요새 폰쪽에 있는 분들... Flash_UI 때문에 난리도 아니죠..^^'


    비주얼 C 프로젝트 쓸일이 있어서

    저도 doxygen 써보려구 생각 중이였는데

    이렇게 글을 올려주셨네요..^^



    한번 써보겠습니다....^^'



    ### 참, 다운로드 경로는 아래를 참고 하세요....^^


    http://ftp.stack.nl/pub/users/dimitri/doxygen-1.5.7.1-setup.exe

    http://www.graphviz.org/pub/graphviz/stable/windows/graphviz-2.22.2.msi





    ^______________^






    [아..^^']

    지금 해봤는데...

    그냥 설치만 하면 되는 게 아니라...

    출력이 되기 위해선 주석을 일정한 형태로

    달아 주어야 하는 과정이 필요하네요...^^'


    개인적으로 작업하는 거나

    오픈소스에서 서로간에 규칙 맞춰서 하는 건 몰라도

    이미 되어 있는 큰 프로젝트의 주석을

    재처리해서 문서화 한다는 건 쉬운 일이 아닌 것 같습니다..^^'



    Doxygen 3.0 정도 출시되면 그런 일이 가능할지도 모르겠지만...^^;




    아쉽네요... 그럼...^^'


    ;
    • 안녕하세요, 스카님. ^^
      와! 그 유명한 프라다폰2 개발에 참여하고 계시는군요. 정말 부럽습니다.
      지금껏 제가 본 핸드폰 중에 당연 최고의 제품으로 생각합니다.
      그 아름다운 제품에 qwerty키보드까지....
      언제 출시될지 궁금합니다만 나와도 저는 구경만 해야 할 것 같아요.
      거의 일백만 원대를 넘어 갈것 같아서 말이죠.
      그런 프라다폰2를 매일 주물럭 거리시겠네요. ^^
    • saviour7
    • 2009.05.14 19:12
    와우~ 정말 굿 입니다!!!
    • 와우
    • 2009.05.16 22:28
    훔쳐갑니다 ^^
  3. 한글이 깨지는 이유에 대해 설명드리겠습니다.
    doxygen이 UTF-8을 기본으로 문서를 작성하는 걸로 보입니다.
    하지만 아마 Windows에서는 소스 파일을 기본적으로 euc-kr로 저장합니다.
    이 인코딩 차이 때문에 한글이 깨지는 것으로 보이네요.

    소스 파일을 저장할 때 UTF-8로 저장하면 한글이 깨지지 않을 것입니다.
  4. 내용을 원저작자 표시하고 그대로 퍼가도 될까요?