doxygen教程-5-编写注释

最新推荐文章于 2024-08-02 16:28:35 发布

qq_28867779

最新推荐文章于 2024-08-02 16:28:35 发布

阅读量534

点赞数

分类专栏： doxygen 教程文章标签： doxygen

doxygen 教程专栏收录该内容

11 篇文章 19 订阅

订阅专栏

文章目录

一些概念

本篇将简要介绍如何编写注释, 在这之前, 让我们先来了解一些概念.

entity

我以为官方会给这个词一个定义的, 但是我搜索了手册, 找到最初几处用到这个词的地方, 发现都没有解释 entity 的含义, 而是直接用了. 不过也不是很难理解, 结合该词出现处的文义来看, entity 就是任何可以被注释的事物的统称: class, function, struct, enum, typedef, member, …

Special comment block

根据手册第 4.1 节的介绍, special comment block 就是用符号标记了的 C/C++ style 的注释块, 因为能被 doxygen 识别, 从而出现在生成的文档中, 所以将其称为 special comment block.

从手册的后文来看, 这也不是需要特别明确定义的概念, 只要知道 special comment block 是要求被 doxygen 识别的注释块就行了.

types of description

因为手册原文写得比较好, 所以我就不废话了, 直接放原文:

For each entity in the code there are two (or in some cases three) types of descriptions, which together form the documentation for that entity; a brief description and detailed description, both are optional. For methods and functions there is also a third type of description, the so called in body description, which consists of the concatenation of all comment blocks found within the body of the method or function. Having more than one brief or detailed description is allowed (but not recommended, as the order in which the descriptions will appear is not specified). As the name suggest, a brief description is a short one-liner, whereas the detailed description provides longer, more detailed documentation. An “in body” description can also act as a detailed description or can describe a collection of implementation details.

大意就是, 每个 entity 的文档都是由两种(有时三种)描述构成的. 对于每个 entity, 都可以有 brief 和 detail 两种描述, 二者都是可选的. 对于函数和方法, 还有第三种描述: in body.

brief 比较简单, 通常只有一行, 而 detail 则是较长的详细描述. in body 将函数体内的注释拼接起来, 作用和 detail 是一样的, 而且更适合揭示函数的实现细节.

注释的格式

我们在前面多次出现的 hello_doxygen 的例子中, 已经见过 brief 和 detail 这两种描述了:

/**
 * @brief   A hello func.
 * @details This hello function does nothing.
 */
void hello(){
    // do nothing
}

brief 和 detail 是最基础的两种描述. 上面的这种注释的格式已经足够使用了, 而除此之外, doxygen 还提供了其他的格式.

detail 的写法

后面我们会介绍 special command. 上面的例子便是分别使用@brief, @details 命令指出注释的内容是属于哪一类描述的.

下面这些风格的注释也是 special comment block. 我们先来混个脸熟.

Javadoc style 的注释
```
/**
 * ... text ...
 */
```
Qt style 的注释
```
/*!
 * ... text ...
 */
```
在这两种风格的注释中, 打头的星号 * 会被忽略掉, 所以下面这种写法是等价的:
```
/*!
  ... text ...
 */
```
至少两行连续的 C++ 注释, 并以额外的斜线/或叹号 ! 开头.
```
///
/// ... text ...
///

//!
//! ... text ...
//!
```
在最初的标准中, C语言注释的语法是 /* */, 而C++注释的语法 //. 在后来的标准中, C/C++ 相互借鉴, 都同时支持两种注释语法.

上面这些注释的内容都会被 doxygen 当作 detail.

需要注意的是, 有些人可能喜欢用一行很长的星号 * 来让注释更明显, 默认情况下, doxygen 不会把这种注释当作 special comment block, 例如:

/******************************
 * 因为注释的开头不是两个星号: /**, 默认情况下这种注释不会被 doxygen 
 * 识别为文档. 如果要使用这种格式, 需要在配置文件中修改
 *     JAVADOC_BANNER = YES
 ******************************/

注: 官方手册上介绍的是在配置文件中添加 JAVADOC_BLOCK = YES, 但是我尝试了, 没有效果. 然后尝试修改 JAVADOC_BANNER = YES, 发现结果正好符合上面的描述.

brief

同样, 除使用 special command 之外, 也有其他方法可以指出一条注释期望被当作 brief 处理.

在配置文件中将 JAVADOC_AUTOBRIEF 设为 YES, 然后用 Javadoc 风格编写注释. 注释中第一个紧跟空格的句点.之前的内容被当作 brief. 例如
```
/** Brief description which ends at this dot. Details follow
* here.
*/
```
对于多行 C++ 注释的风格同样可以使用这一方法:
```
/// Brief description which ends at this dot. Details follow
/// here.
```
问题1: 这里没提到 Qt style, 那 Qt style 是不是不行呢? 实际测试发现 Qt style 的注释用这招确实没作用.

问题2: 要是句点. 后面没有空格呢? 实际测试发现, 那就是视为 brief 还未结束, 直到遇到第一个句点. 后紧跟空格的位置. 该位置之前的内容全部被视为 brief.
只有一行的单行注释(即前文所称的C++注释), 例如
```
/// Brief description.
/** Detailed description. */
```
或者
```
//! Brief description.

//! Detailed description
//! starts here.
```
在第二个例子中, 第一块注释只有一行单行注释, 因而被当作 brief 处理, 而第二块注释则是连续的两行单行注释, 由前文所知, 这是个 detail.

可见, 多行注释 /* */ 都是 detail.

注释拼接

对于多块相邻的 detailed description, doxygen 会将它们拼接成一个. 例如

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

小结

恭喜你耐住性子看到了这里, 茴香豆的"茴"字有四种写法, doxygen 的 detail 却有 5 种写法, 让人眼花缭乱. 在费了不少力气理解了这些写法之后, 相信你也感觉到了, 自己好像学到了什么, 又好像什么都没有学到 —— 显然, 第一种应用 special command 的写法完全足够使用, 所有其他的写法都是等价的!