KLDPWiki: Doxygen/강좌03

Doxygen/강좌03

1.3.2.1. Section구분자
1.3.2.2. 화면에 출력될 Section명
1.3.2.3. -

2. 긴 설명 쓰기

2.1. 예제1
2.2. 예제2

3. struct(class), enum 문서화

4. define, 전역변수

5. 지금까지 한 전체 소스

6. 지금까지의 문서화 예제 링크

7. 맺음말

8. 게시판

[edit]

1. Main Page 작성 ¶

Main Page는 무엇인가 하면 바로 Doxygen한 문서에서 첫화면에서 나오는 화면을 작성(장식)하는것이다.

왜 작성을 하는가 하면 이문서는 무엇을 설명하는가와 차례, 작성자, 작성날짜, 수정정보등 기타 정보를 보여주기 위함이다.(개인적으로는 작성자쓰는것을 -_-;;)

음음.. 각설하고 이제 한번 저번의 main화면을 다시 보겠다.

뭔가 허전하지 않는가? 보통 이곳이 멋져야 폼이 난다(-_-;).

그럼 이곳을 멋있게 장식해 보겠다. 일단 helo.c에 한번 문서화를 해보자.

[edit]

1.1. 소스 작성 ¶

  /**
   @file     hello.c
   @brief    hello world  소스파일.
   */

  /**
    @mainpage   Hello World 메인페이지
    @section intro 소개
    - 소개      :   프로그램의 기본을 배울수있는 프로그램.
    @section   Program 프로그램명
    - 프로그램명  :   Hello World 프로그램.
    - 프로그램내용    :   화면에 Hello World!을 출력한다.
    @section  INOUTPUT    입출력자료
    - INPUT           :   없음.
    - OUTPUT      :   Hello World 화면출력.
    @section  CREATEINFO      작성정보
    - 작성자      :   infiniterun
    - 작성일      :   2005/04/18
    @section  MODIFYINFO      수정정보
    - 수정자/수정일   : 수정내역
    - infiniterun/2005.0418    :   "Helo World"에 "!"추가
    */

  #include <stdio.h>

  /**
   @brief     hello Main 함수.
   @return    성공여부.
   */
  int main(
      int    argc,       /**< 인자개수 */
      char * argv[]      /**< 인자 */
      )
  {
       printf("Hello World!\n");
       return 0;
  }

[edit]

1.2. 문서화 ¶

문서화 하는 방법은 1회 강좌에서

http://wiki.kldp.org/wiki.php/Doxygen/%B0%AD%C1%C201?action=download&value=doxywizard_start.gif

[GIF external image]

여기서 Step 1 에 Load...버튼을 클릭하여 저번에 저장한 D:\Doxygen\Doxyfile을 읽어 들이면 된다.(모르겠다면 1회 강좌 3.3 문서화하기를 그대로 다시 해보아라.)
그리고 Step 4의 Start를 눌러 문서화를 한다.

이제 아래를 보자.

전화면과 많이 바뀐걸 알수 있다. 이제 이것을 설명하겠다.

[edit]

1.3. 설명 ¶

[edit]

1.3.1. @mainpage ¶

   /**
   @mainpage    Main화면에 출력될 메시지(한글영문 모두 가능)
   ...
   */

/** 는 Doxygen구문이 시작된다는것이고 @mainpage 는 아래 Doxygen구문이 MainPage을 나타낸다는것이다.

[edit]

1.3.2. @section ¶

   /**
   ...
   @section intro 소개
   - 소개      :   프로그램의 기본을 배울수있는 프로그램.

   @section Section구분자   화면에 출력될 Section명.
   - 설명(한글 영문 모두 가능하며 아무거나 쓰면됨
   */

[edit]

1.3.2.1. Section구분자 ¶

영문만 가능하며 Section을 구분하기위한 표시이다. 한글은 안된다.(필자도 잘 모르겠다.)

그냥 하무거나 써도 된다(section1, section2, ... 등등등..)

[edit]

1.3.2.2. 화면에 출력될 Section명 ¶

한글도 가능하며 소재목이 될 것을 쓴다.(예. 소개, 작성자정보, 수정정보등.)

[edit]

1.3.2.3. - ¶

그냥 워드에서 말하는 번호매기기 등과 같다. 한줄 한줄 설명을 쓰기위해 쓴다고 보면 된다.

[edit]

2. 긴 설명 쓰기 ¶

보통 함수 설명을 할때 brief는 간단한 설명을 쓰는것이고 반드시 한줄이내에 써야한다.

@brief에서 엔터(\n 포함)가 들어가면 안된다.

그래서 필요한것이 여러줄 설명, 긴줄 설명인데 이 여러줄 설명은

@brief 아래 빈줄 하나를 두고 설명을 쓴다.

[edit]

2.1. 예제1 ¶

  /**
   @brief     hello Main 함수.

   긴 설명은 한줄을 넘긴다음 넣어준다. \n
   하나둘. 셋.. 넷.. 
   다섯.. 여섯.. \n

   @return    성공여부.
   */
  int main(
      int    argc,       /**< 인자개수 */
      char * argv[]      /**< 인자 */
      )
  {

주의 할것은 위의 것중 끝에 \n이 붙어 있는것만 문서화에서 엔터가 들어간다는 것이다.

위의

  /**
  ...
  긴 설명은 한줄을 넘긴다음 넣어준다. \n
  하나둘. 셋.. 넷.. 
  다섯.. 여섯.. \n
  */

은

  긴 설명은 한줄을 넘긴다음 넣어준다.
  하나둘. 셋.. 넷..  다섯.. 여섯..

이렇게 나온다.(엔터가 없고 대신 스페이스바가 하나 들어간다.)

[edit]

2.2. 예제2 ¶

  /**
   @file     hello.c
   @brief    hello world  소스파일.

   파일여러줄 설명입니다.\n
   진짜 여러줄 입니다.\n
   음.. 하나. 둘. 셋
   넷다섯.
   */

[edit]

3. struct(class), enum 문서화 ¶

이제 아래 예제만 보면 거의 이해가 될것이다.

 /**
  @brief buffer structor
 
  Telnet에서 정송되는 데이터에 대해 프로토콜을 처리해야 하기 위하여,
  효율적으로 데이터를 전송해야 할 입출력 버퍼 structor
 */
 struct  buffer
 {
         char       *buf;   /**< 데이터를 저장할 주소공간   */
         int        size;   /**< buf에 할당된 메모리 크기   */
         int        head;   /**< buf에 저장된 데이터의 처음 Index   */
         int        tail;   /**< buf에 저장된 데이터의 마지막 index */
         int        count;  /**< buf에 저장된 데이터의 byte 수      */
 };


 /** @brief TRUE FALSE정의. */
 enum BOOLEAN
 {
    FALSE=0,        /**< FALSE */
    TRUE            /**< TRUE */
 };

struct buffer 문서화
enum BOOLEAN 문서화

/**< */ 는 앞에 있는 변수나 어떤 인자를 설명하는 것이다.

나머지는 앞에서 설명이 다 되었기 때문에 설명을 생각하겠다.

[edit]

4. define, 전역변수 ¶

 #define MAX_READ_BUF   1024    /**< 최대 read buffer size      */

 short  port;                   /**< Telnet port number */

define, 전역변수 문서화

앞에서 설명이 다 된 내용이다.

[edit]

5. 지금까지 한 전체 소스 ¶

/**
  @file     hello.c
  @brief    hello world  소스파일.

  파일여러줄 설명입니다.\n
  진짜 여러줄 입니다.\n
  음.. 하나. 둘. 셋
  넷다섯.
  */

/**
  @mainpage   Hello World 메인페이지
  @section intro 소개
  - 소개      :   프로그램의 기본을 배울수있는 프로그램.
  @section   Program 프로그램명
  - 프로그램명  :   Hello World 프로그램.
  - 프로그램내용    :   화면에 Hello World!을 출력한다.
  @section  INOUTPUT    입출력자료
  - INPUT           :   없음.
  - OUTPUT      :   Hello World 화면출력.
  @section  CREATEINFO      작성정보
  - 작성자      :   infiniterun
  - 작성일      :   2005/04/18
  @section  MODIFYINFO      수정정보
  - 수정자/수정일   : 수정내역
  - infiniterun/2005.0418    :   "Helo World"에 "!"추가
  */

#include <stdio.h>


#define MAX_READ_BUF   1024    /**< 최대 read buffer size      */

short  port;                   /**< Telnet port number */

/**
  @brief buffer structor

  Telnet에서 정송되는 데이터에 대해 프로토콜을 처리해야 하기 위하여,
  효율적으로 데이터를 전송해야 할 입출력 버퍼 structor
  */
struct  buffer
{
    char       *buf;   /**< 데이터를 저장할 주소공간   */
    int        size;   /**< buf에 할당된 메모리 크기   */
    int        head;   /**< buf에 저장된 데이터의 처음 Index   */
    int        tail;   /**< buf에 저장된 데이터의 마지막 index */
    int        count;  /**< buf에 저장된 데이터의 byte 수      */
};

/** @brief TRUE FALSE정의. */
enum BOOLEAN
{
    FALSE=0,        /**< FALSE */
    TRUE            /**< TRUE */
};

/**
  @brief     hello Main 함수.

  긴 설명은 한줄을 넘긴다음 넣어준다. \n
  하나둘. 셋.. 넷.. 
  다섯.. 여섯.. \n

  @return    성공여부.
  */
int main(
        int    argc,       /**< 인자개수 */
        char * argv[]      /**< 인자 */
        )
{
    printf("Hello World!\n");
    return 0;
}