Doxygen 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++ 주석에서도 같은 효과를 가집니다.

/// 간략설명은 다음 마침표까지로 간주합니다. 상세 설명은
/// 지금부터 처리됩니다.

세번째 옵션은 하나이상의 라인을 스펜(span)하지 않는 특별한 C++ 스타일 주석을 사용하는 것입니다. 여기에 2가지 예제가 있습니다:

/// Brief description.
/** Detailed description. */

또는

//! Brief descripion.

//! Detailed description 
//! starts here.

상세설명을 포함하고 있는 블럭을 간단히 설명하기 위해서 마지막 예에서 빈라인을 이용하였다.
이경우에는 <color blue>JAVADOC_AUTOBRIEF</color> 옵션이 NO 이어야 한다.

doxygen는 매우 유연한 프로그램이다. 다중상세설명을 원한다면, 다음 예제를 참고하면 된다:

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

They will be joined. Note that this is also the case if the descriptions are at different places in the code! In this case the order will depend on the order in which doxygen parses the code.

Qt 스타일을 이용하여 C++ 코딩을 주석화 한 예이다:

//!  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);
};

doxygen에 의해 생성되는 해당 HTML 문서를 보려면 여기를 클릭하십시오.

멀티 라인 주석 블록에 대한 자세한 설명을 포함하는 반면 한 라인 주석은 간단한 설명이 포함되어 있습니다.

간략설명(brief descriptions)은 class, namespace, file 의 멤버 개요가 포함되어 있으며 작은 기울임꼴 글꼴을 사용하여 인쇄됩니다 (이 설명은 설정파일에서 BRIEF_MEMBER_DESC 값이 NO로 숨길 수 있습니다.)
기본적으로 간략설명은 상세설명의 첫문장에 옵니다. (그러나 REPEAT_BRIEF 값을 NO로 변경할 수 있습니다).
간략설명과 상세설명 모두 Qt 스타일의 옵션입니다.

기본적으로 JavaDoc 스타일의 문서 블록은 Qt는 스타일 문서 블록과 같은 방식으로 동작합니다. JavaDoc은 명시적으로 문서의 첫번째 블록에 간략설명되지 않아도 상관없다.(This is not according the JavaDoc specification however, where the first sentence of the documentation block is automatically treated as a brief description.) 이 동작을 사용하려면 JAVADOC_AUTOBRIEF 을 YES로 설정해야 한다.
만약 이 옵션을 활성화하고 끝나지 않은 문장의 중간에 점(dot)을 넣으려는 경우에는, 점뒤에 백슬래시(backslash)와 공간(space)를 붙여야 합니다. 그 예이다:

/** Brief description (e.g.\ using only a few words). Details follow. */

Here is the same piece of code as shown above, this time documented using the JavaDoc style and JAVADOC_AUTOBRIEF set to YES:

/**
 *  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. */  
         } 
       *enumPtr, /**< enum pointer. Details. */
       enumVar;  /**< enum variable. Details. */
       
      /**
       * 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.
       * @see Test()
       * @see ~Test()
       * @see testMeToo()
       * @see publicVar()
       * @return The test results
       */
       int testMe(int a,const char *s);
       
      /**
       * A pure virtual member.
       * @see 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);
};

doxygen에 의해 생성되는 해당 HTML 문서를 보려면 여기를 클릭하십시오.

대부분의 다른 문서와 달리 doxygen은 정의 앞에 member의 문서(global functions 포함)을 넣을 수 있다.
이 방법을 통해서 문서를 헤더파일 대신 소스파일에 놓을 수 있다.
이 방법은 header를 컴팩트(compact)하게 하고, 문서를 더 많이 직접접근(direct access)하게 하는 맴버의 시행(implementer)을 허락한다.
간략설명은 선언(declaration)전엔 놓일 수 있고, 상세설명은 맴버정의(member definition)전에 놓일 수 있게 절충(compromise)할 수 있다.

If you want to document the members of a file, struct, union, class, or enum, and you want to put the documentation for these members inside the compound, it is sometimes desired to place the documentation block after the member instead of before. For this purpose you should put an additional < marker in the comment block. Here are some examples:

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

This block can be used to put a Qt style detailed documentation block after a member. Other ways to do the same are:

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

또는

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

또는

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

Most often one only wants to put a brief description after a member. This is done as follows:

int var; //!< Brief description after the member

또는

 
int var; ///< Brief description after the member

Note that these blocks have the same structure and meaning as the special comment blocks in the previous section only the < indicates that the member is located in front of the block instead of after the block.

Here is an example of the use of these comment blocks:

/*! A test class */

class Test
{
  public:
    /** An enum type. 
     *  The documentation block cannot be put after the enum! 
     */
    enum EnumType
    {
      int EVal1,     /**< enum value 1 */
      int EVal2      /**< enum value 2 */
    };
    void member();   //!< a member function.
    
  protected:
    int value;       /*!< an integer value */
};

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

These blocks can only be used to document members and parameters. They cannot be used to document files, classes, unions, structs, groups, namespaces and enums themselves. Furthermore, the structural commands mentioned in the next section (like \class) are ignored inside these comment blocks.

So far we have assumed that the documentation blocks are always located in front of the declaration or definition of a file, class or namespace or in front or after one of its members. Although this is often comfortable, there may sometimes be reasons to put the documentation somewhere else. For documenting a file this is even required since there is no such thing as “in front of a file”. Doxygen allows you to put your documentation blocks practically anywhere (the exception is inside the body of a function or inside a normal C style comment block). The price you pay for not putting the documentation block before (or after) an item is the need to put a structural command inside the documentation block, which leads to some duplication of information.

uctural commands (like all other commands) start with a backslash (\), or an at-sign (@) if you prefer JavaDoc style, followed by a command name and one or more parameters. For instance, if you want to document the class Test in the example above, you could have also put the following documentation block somewhere in the input that is read by doxygen:

/*! \class Test
    \brief A test class.

    A more detailed class description.
*/

Here the special command \class is used to indicate that the comment block contains documentation for the class Test. Other structural commands are:

\struct to document a C-struct. 
\union to document a union. 
\enum to document an enumeration type. 
\fn to document a function. 
\var to document a variable or typedef or enum value. 
\def to document a #define. 
\file to document a file. 
\namespace to document a namespace. 
\package to document a Java package. 
\interface to document an IDL interface. 

See section Special Commands for detailed information about these and many other commands.

To document a member of a C++ class, you must also document the class itself. The same holds for namespaces. To document a global C function, typedef, enum or preprocessor definition you must first document the file that contains it (usually this will be a header file, because that file contains the information that is exported to other source files).

Let's repeat that, because it is often overlooked: to document global objects (functions, typedefs, enum, macros, etc), you must document the file in which they are defined. In other words, there must at least be a

/*! \file */ 

또는

 /** @file */ 

Here is an example of a C header named structcmd.h that is documented using structural commands:

/*! \file structcmd.h
    \brief A Documented file.
    
    Details.
*/

/*! \def MAX(a,b)
    \brief A macro that returns the maximum of \a a and \a b.
   
    Details.
*/

/*! \var typedef unsigned int UINT32
    \brief A type definition for a .
    
    Details.
*/

/*! \var int errno
    \brief Contains the last error code.

    \warning Not thread safe!
*/

/*! \fn int open(const char *pathname,int flags)
    \brief Opens a file descriptor.

    \param pathname The name of the descriptor.
    \param flags Opening flags.
*/

/*! \fn int close(int fd)
    \brief Closes the file descriptor \a fd.
    \param fd The descriptor to close.
*/

/*! \fn size_t write(int fd,const char *buf, size_t count)
    \brief Writes \a count bytes from \a buf to the filedescriptor \a fd.
    \param fd The descriptor to write to.
    \param buf The data buffer to write.
    \param count The number of bytes to write.
*/

/*! \fn int read(int fd,char *buf,size_t count)
    \brief Read bytes from a file descriptor.
    \param fd The descriptor to read from.
    \param buf The buffer to read into.
    \param count The number of bytes to read.
*/

#define MAX(a,b) (((a)>(b))?(a):(b))
typedef unsigned int UINT32;
int errno;
int open(const char *,int);
int close(int);
size_t write(int,const char *, size_t);
int read(int,char *,size_t);

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

Because each comment block in the example above contains a structural command, all the comment blocks could be moved to another location or input file (the source file for instance), without affecting the generated documentation. The disadvantage of this approach is that prototypes are duplicated, so all changes have to be made twice! Because of this you should first consider if this is really needed, and avoid structural commands if possible. I often receive examples that contain \fn command in comment blocks which are place in front of a function. This is clearly a case where the \fn command is redundant and will only lead to problems.

가끔 클래스 링크가 생성되지 않을 때가 있습니다.
(예 : 템플릿내에서 해당 맴버를 참조할 경우 맴버에서는 자동으로 해당 템플릿 함수, 클래스의 링크는 생성되지 않습니다)
이럴때에는 @ref 명령으로 강제로 링크를 설정할 수 있습니다.
(이때 주의할 점은 반드시 링크가 존재해야합니다)
강제로 주석중에 참조링크를 넣고 싶을때도 좋습니다.
이때 링크는 클래스명이 적당할 것입니다.

/**
 @brief 내부용으로 사용되는 sprite 부모 (추상) 클래스.
 
 lua_group, @ref lua_depth에 적용가능한 모든 sprite 클래스는 이 클래스에서 상속받아
 구현합니다. 기본적으로 이 클래스는 lua에 바인딩되지 않고 C/C++에서만 사용합니다. 
*/

주석 블럭안에 C/C++ 예제 소스코드를 넣고 싶다면 @code … @endcode 로 소스를 감싸주면 됩니다.