문서의 이전 판입니다!

Doxygen Special Documentation Blocks

special documentation blocks

special documentation blocks(SDB)은 몇몇 추가된 표시를 가진 C 또는 C++ 주석 블럭을 말하며, 이렇게 함으로서 doxygen은 생성될 문서내에 표시될 문서 부분을 알수 있게 됩니다.
각각의 코드 아이템에 대하여 두가지 설명 형식이 존재하며, 이들이 모두 묶여서 문서를 형성하게 됩니다 : 간략 설명, 상세 설명을 말하며, 이들 모두 선택사항입니다.
그러나 하나 이상의 간략 또는 상세 설명을 가지는 것은 허용되지 않습니다.
용어 뜻에서 알 수 있듯이, 간략 설명은 짧은 한줄짜리 설명을 말하며 상세 설명은 더 길고 더 상세한 문서를 제공합니다.

상세설명 주석블럭 표시방법

두개의 '*'으로 시작하는 C스타일 주석문을 포함함으로서 JavaDoc 스타일을 다음과 같이 사용할 수 있습니다
```
/**
 * ... 문장 ...
 */
```
또는 Qt 스타일을 사용할 수 있습니다. 이때는 아래 예와 같이 C 스타일 주석문처음에 ! 문자를 추가합니다.
```
/*!
 * ... 문장 ...
 */
```
중간의 '*'문자는 선택사항입니다. 즉, 다음과 같이 해도 적법하게 처리합니다. (redpixel이 선호하는 방법)
```
/*!
 ... 문장 ...
*/
```
세번째 방법은 최소 두개의 C++ 주석 줄을 붙여 사용하는 방법입니다.
이때 각 줄은 <color red>//</color> 다음에 <color red>/</color>나 <color red>!</color>문자를 하나 더 붙여주어야합니다.
```
///
/// ... 문장 ...
///
```
또는
```
//!
//!... 문장 ...
//!
```
몇몇 개발자들은 문서안에서 더 눈에 띄도록 주석 블럭을 만들기를 좋아합니다. 이렇게 하려면 다음과 같이 합니다
```
/////////////////////////////////////////////////
/// ... 문장 ...
/////////////////////////////////////////////////
```

간략설명 주석블럭 표시방법

@brief 명령을 주석 블럭의 상단에 넣는 방법입니다.
이 명령은 단락의 끝에서 효과가 종료됩니다.
그러므로 간략 설명을 넣고 한줄 띄워줘야 그 이후를 세부설명으로 간주하게 됩니다.
```
/*! \brief 간략설명.
 *         계속된 간략설명.
 *
 *  세부설명 시작.
 */
```
JAVADOC_AUTOBRIEF를 YES로 설정했다면, javaDoc 스타일 블럭방식을 사용할 경우 자동적으로 첫번째 문장(.으로 끝나는 문장)을 간략설명으로 간주합니다.
```
/** 간략설명은 다음 마침표까지로 간주합니다. 상세 설명은
 *  지금부터 처리됩니다.
 */
```
이 옵션은 여러줄의 C++ 주석에서도 같은 효과를 가집니다.
```
/// 간략설명은 다음 마침표까지로 간주합니다. 상세 설명은
/// 지금부터 처리됩니다.
```
A third option is to use a special C++ style comment which does not span more than one line. Here are two examples:
```
/// Brief description.
/** Detailed description. */
```
또는
```
//! Brief descripion.

//! Detailed description 
//! starts here.
```
Note the blank line in the last example, which is required to separate the brief description from the block containing the detailed description.
The JAVADOC_AUTOBRIEF should also be set to NO for this case.

주의사항

As you can see doxygen is quite flexible. The following however is not legal

//! Brief description, which is
//! really a detailed description since it spans multiple lines.
/*! Oops, another detailed description!
 */

Furthermore, if there is one brief description before a declaration and one before a definition of a code item, only the one before the declaration will be used. If the same situation occurs for a detailed description, the one before the definition is preferred and the one before the declaration will be ignored.

Here is an example of a documented piece of C++ code using the Qt style:

//!  A test class. 
/*!
  A more elaborate class description.
*/

class Test
{
  public:

    //! An enum.
    /*! More detailed enum description. */
    enum TEnum { 
                 TVal1, /*!< Enum value TVal1. */  
                 TVal2, /*!< Enum value TVal2. */  
                 TVal3  /*!< Enum value TVal3. */  
               } 
         //! Enum pointer.
         /*! Details. */
         *enumPtr, 
         //! Enum variable.
         /*! Details. */
         enumVar;  
    
    //! A constructor.
    /*!
      A more elaborate description of the constructor.
    */
    Test();

    //! A destructor.
    /*!
      A more elaborate description of the destructor.
    */
   ~Test();
    
    //! A normal member taking two arguments and returning an integer value.
    /*!
      \param a an integer argument.
      \param s a constant character pointer.
      \return The test results
      \sa Test(), ~Test(), testMeToo() and publicVar()
    */
    int testMe(int a,const char *s);
       
    //! A pure virtual member.
    /*!
      \sa testMe()
      \param c1 the first argument.
      \param c2 the second argument.
    */
    virtual void testMeToo(char c1,char c2) = 0;
   
    //! A public variable.
    /*!
      Details.
    */
    int publicVar;
       
    //! A function variable.
    /*!
      Details.
    */
    int (*handler)(int a,int b);
};

Click here for the corresponding HTML documentation that is generated by doxygen.

The one-line comments contain a brief description, whereas the multi-line comment blocks contain a more detailed description.

The brief descriptions are included in the member overview of a class, namespace or file and are printed using a small italic font (this description can be hidden by setting BRIEF_MEMBER_DESC to NO in the config file). By default the brief descriptions become the first sentence of the detailed descriptions (but this can be changed by setting the REPEAT_BRIEF tag to NO). Both the brief and the detailed descriptions are optional for the Qt style.

By default a JavaDoc style documentation block behaves the same way as a Qt style documentation block. This is not according the JavaDoc specification however, where the first sentence of the documentation block is automatically treated as a brief description. To enable this behaviour you should set JAVADOC_AUTOBRIEF to YES in the configuration file. If you enable this option and want to put a dot in the middle of a sentence without ending it, you should put a backslash and a space after it. Here is an example:

adminschool.net wiki

목차

Doxygen Special Documentation Blocks

special documentation blocks

상세설명 주석블럭 표시방법

간략설명 주석블럭 표시방법

주의사항