到目前为止,我们都是使用 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!