doxygen 代码文档样式

到目前为止，我们都是使用 doxygen 从原本没有文档的代码中提取信息。但是，doxygen 也鼓励使用文档样式和语法，这有助于生成更详细的文档。本节讨论 doxygen 鼓励在 C/C++ 代码中使用的一些常用标记。更多信息参见 参考资料。

每个代码元素有两种描述：简短的和详细的。简短描述通常是单行的。函数和类方法还有第三种描述体内描述（in-body description），这种描述把在函数体中找到的所有注释块集中在一起。比较常用的一些 doxygen 标记和注释样式如下：

• 简短描述：使用单行的 C++ 注释，或使用 <\brief> 标记。
• 详细描述：使用 JavaDoc 式的注释 /** … test … */（注意开头的两个星号 [*]）或 Qt 式的注释 /*! … text … */。
• 体内描述：类、结构、联合体和名称空间等 C++ 元素都有自己的标记，比如 <\class>、<\struct>、<\union> 和 <\namespace>。

为了为全局函数、变量和枚举类型生成文档，必须先对对应的文件使用 <\file> 标记。清单 12 给出的示例包含用于四种元素的标记：函数标记（<\fn>）、函数参数标记（<\param>）、变量名标记（<\var>）、用于 #define 的标记（<\def>）以及用来表示与一个代码片段相关的问题的标记（<\warning>）。

清单 12. 典型的 doxygen 标记及其使用方法

/*! \file globaldecls.h \brief Place to look for global variables, enums, functions and macro definitions */ /** \var const int fileSize \brief Default size of the file on disk */ const int fileSize = 1048576; /** \def SHIFT(value, length) \brief Left shift value by length in bits */ #define SHIFT(value, length) ((value) << (length)) /** \fn bool check_for_io_errors(FILE* fp) \brief Checks if a file is corrupted or not \param fp Pointer to an already opened file \warning Not thread safe! */ bool check_for_io_errors(FILE* fp);

下面是生成的文档：

                Defines
#define SHIFT(value, length)   ((value) << (length))  
             Left shift value by length in bits.

Functions
bool check_for_io_errors (FILE *fp)  
        Checks if a file is corrupted or not.

Variables
const int fileSize = 1048576;
Function Documentation
bool check_for_io_errors (FILE* fp)
Checks if a file is corrupted or not.

Parameters
              fp: Pointer to an already opened file

Warning
Not thread safe!