Doxygen을 활용한 코드 문서화

Doxygen을 활용한 코드 문서화

Chapter - 1 주석

• 주석의 중요성 

1. 큰 프로젝트에서는 소스코드를 분석하는데 있어 주석이 없으면 효율성이 떨어진다.(물론 가독성이 좋고 잘짜여진 소스코드면 주석이 따로 필요없다 ,-.- 이런 코드 단 한번도 못봄...)
2. 코드에 대한 빠른 이해를 돕니다.
3. 한달이 지난 코드는 새로운 코드 처럼 느껴진다. 
4. 유지 보수를 위해서 꼭 필요하다. 
5. 주석이 없는 코드는 다른 사람들이 보기가 힘들다.

• 주석의 유의사항 
• 너무 과하게 달지만 말아라.
• 주석은 코드의 이해를 돕는거지 코드를 자세하게 설명하는게 아니다.

Chapter - 2 문서화 도구 Doxygen

• 코드 문서화를 위한 도구(doxygen + graphviz)
• doxygen: 소스코드 문서화 도구
• 지원 언어  C, C++, C#, Objective-C, IDL, Java, VHDL, PHP, Python, Tcl, Fortran, and D
• 다운로드 링크
• graphviz: 소스코드 문서화시 그래프, 다이어그램 표시 지원 툴
• 다운로드 링크
• Doxygen 설치 (Linux 기준)

• tar -zxvf doxygen-1.5.9.linux.bin.tar.gz

  cd doxygen-1.5.9

  ./configure

  make && make install

• graphviz 설치 (Linux 기준)

• tar -zxvf graphviz-2.6.tar.gz

  cd graphviz-2.6

  ./configure

  make && make install

Chapter - 3 Doxygen 기본 사용법

• Doxygen 사용법
• Doxygen을 이용하여문서를 만들기 위해서 설정 파일이 피요하다.
• 설정 파일 생성 방법
• #doxygen -g "생성될 설정파일명 입력
• Doxygen 설정 파일 세팅 
• 설정 파일에대한 공식 설명서
• 설명서
• 세팅 파일 구조 
• Makefie 과 유사한 구조이다. 
• TAGNAME = VALUE or 
  TAGNAME = VALUE1 VALUE2 ... 
• 필수 설정 파일 설명
• DOXYFILE_ENCODING = UTF-8 => EUC-KR
• INPUT_ENCODING     = euc-kr  <=한글표시하기위한 필수
• PROJECT_NAME = 프로젝트명
• PROJECT_NUMBER = 프로젝트버전
• OUTPUT_DIRECTORY = 파일을 저장할 위치
• EXTRACT_ALL = 모든 함수를 문서화 
• EXTRACT_STATIC = static 정보를 보여줄지 결정
• SOURCE_BROWSER = NO =>YES // 소스코드를 보여준다.
• HAVE_DOT = NO =>YES  //graphviz 사용
• CALL_GRAPH = NO =>YES   //call관계를 그래프로 보여준다 
• CALLER_GRAPH = NO =>YES //caller 관계를 그래프로 보여준다.
• DOT_PATH = => XX/graphviz-2.6/cmd/dot //graphviz 실행파일 경로
• ( graphviz를 설치하면 설치된 디렉토리 아래 cmd/dot에 dot라는 실행 파일이 생성이 된다. 그 디렉토리명을 입력하면 된다.)
• INPUT = 소스파일 경로(여러 디렉토리인 경우 모든 경로를 다 지정한다. 공백으로 구분)
• RECURSIVE = 서브폴더에 있는 소스도 포함할지 여부
• GENERATE_HTMLHELP = chm 파일(Windows Help 파일)을 생성할 때 YES로 지정합니다. 이 때 다음 항목들이 추가로 지정해야 함.
•  - CHM_FILE = 생성될 chm 파일명을 지정
•  - HHC_LOCATION = hhc.exe 파일 패스(HTML Help Compiler. MS에서 HTML Help Workshop을 다운로드해서 설치.)
• INPUT                         = test.c sn_worker.c
• INCLUDE_PATH = input 파일은 아니나 전처리에 필요한 파일들 경로(여러 디렉토리인 경우 모든 경로를 다 지정한다. 공백으로 구분)
• INCLUDE_FILE_PATTERNS = *.h
• EXCLUDE = INPUT tag에서 걸러낼 파일 및 디렉토리
• EXCLUDE_PATTERNS = INPUT tag 디렉토리에서 제거할 패턴

Ex)Doxygen Config 설정 예제

• DOXYFILE_ENCODING       = UTF-8
• INPUT_ENCODING           = euc-kr  <=한글표시하기위한 필수
• OUTPUT_DIRECTORY        = 파일을 저장할 위치
• PROJECT_NAME               = TEST
• PROJECT_NUMBER           = 0.1
• EXTRACT_ALL                  = YES
• EXTRACT_STATIC             = YES
• RECURSIVE                     = YES
• SOURCE_BROWSER          = YES
• GENERATE_TREEVIEW      = YES
• HAVE_DOT                    = YES
• UML_LOOK                   = YES
• CALL_GRAPH                 = YES
• CALLER_GRAPH              = YES
• DOT_PATH                    = /usr/bin/dot
• DOT_GRAPH_MAX_NODES    = 1
• INPUT                           = test.c sn_worker.c src include 
• FILE_PATTERNS               = *.c *.h
• OUTPUT_LANGUAGE        = Korea

• Doxygen 사용 결과 보기
• 결과물 생성 형태

• HTML 

• LaTeX 

• RTF 

• XML 

• Man page

• DocBook

Chapter - 4 Doxygen 주석 다는 스타일(JavaDoc style(C기준))

• C Style 주석 ( 공식문서에 쓰여져 있음)
• You can use the JavaDoc style, which consist of a C-style comment block starting with two *'s, like this:

• /**
   * ... text ...
   */

• 대부분의 Doxygen 페이지에 Qt Style일로 작성 되어 있어..참고 사항으로추가.                   

• Qt Style을 /** 이를 /*! 이렇게만 바꾸면 된다.
• or you can use the Qt style and add an exclamation mark (!) after the opening of a C-style comment block, as shown in this example:

• /*!
   * ... text ...
   */
  

  In both cases the intermediate *'s are optional, so

  /*!
   ... text ...
  */

• 함수 내부 변수에 주석 다는 방법(2개의 스타일을 추천) 
• 아래 두개중 맘에 드는 거 쓰기.

• int var; /**< Detailed description after the member */

• int var; ///< Detailed description after the member
           ///< 

• 함수 파라미터에 주석 달기 

• void foo(int v /**< [in] docs for input parameter v. */);