Doxygen：类C语言的注释块

 所用版本为doxygen1.8.0

 

对于代码中的每个entity，有两种类型的description，这两种description一起形成了该entity的文档，即：

• brief description：只有简短的一行。
• detailed description：更长、更详细的文档。

而对于方法和函数，还有第三种description："in body" description，由方法或函数中的所有注释块组成。

对HTML来说，当一个item被引用时，output brief descriptions用来提供tooltips。

如何将一个注释块标记为detailed description？

1. 使用JavaDoc风格。以两个星号*开始的C-风格注释块。

/**
* detailed description: JavaDoc style
*/

2. 使用Qt风格，在C风格注释块的开始处加上一个感叹号!。

/*!
* detailed description: Qt style
*/

这两种方法中，中间的*是可以省略的，

/*!
detailed description
*/

3. 用至少两个C++注释行，每行的开始增加一个/或!。

///
/// detailed description
///

 或

//!
//! detailed description
//!

注意：这种情况下，用一个空行来结束一个文档块。

4. 有些人喜欢对注释块进行标记，使其在文档中比较明显。

/*****************************//**
* detailed description
*********************************/

在第一行的结尾，用两个星号来结束正常的注释块，并开始一个特殊的注释块。

也可以写成：

/
/// detailed description
/

如何将一个注释块标记为detailed description？

1. 在上述的注释块中使用命令\brief。该命令到一段的结束为止，因此detailed description要放在一个空行之后。

/*! \brief Brief description.
*             Also brief description
*
* Detailed description
*/

2. 如果在配置文件中JAVADOC_AUTOBRIEF设为YES，或在wizard勾选，使用JavaDoc风格的注释块，将会自动将第一个dot（点）之前的内容作为brief description，这里dot后边必须跟有空格或新的一行。

/** Brief description ends at this dot.
* Detailed description
*/

该选项对多行的特殊C++注释有同样的效果：

/// Brief description ends at this dot.
/// Detailed description

3. 使用特殊的C++风格注释，不能超过一行。

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

也可以：

//! Brief description

//! Detailed description
//! continue

Brief descripiton和Detailed description中间的空行是用来区分这两个description的。这种情况下，JAVADOC_AUTOBRIEF要设为NO。

Doxygen还允许用户将成员（包括全局函数）的文档放在定义之前。在这种方法中，文档被放在源文件中而不是头文件中。这样，不但能够保证头文件的紧致，还能让成员的使用者更直接的访问文档。

一般来说，会将brief description放在声明之前，而将detailed description放在成员定义之前。

将文档放在成员之后 (Putting documentation after members)

当想对一个文件、struct、union、class或enum中的成员进行记载时，有时希望将文档块放在成员的后面。

这时，必须在注释块中加入一个 < 标记。Note：对于函数的参数也一样可以这么做。

例1：

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

这是将一个Qt 风格的detailed 文档块放在一个成员后面。

其他方法有：

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

或：

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

或：

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

 

在生成的html中，效果是：

大多数时，只想在成员后放一个brief description。可以：

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

或：

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

在生成的html中，效果是：

~~~~

函数中如何使用待续