doxygen教程-7-special commands

在前面的文章中, 我们已经多次用到了 @brief, @details, @file 这几个命令. 本文将具体地介绍这些命令是如何工作的. doxygen 提供了大量的指令 并介绍一些常用的命令以供参考.

以下内容整理自官方手册 doxygen_manual-1.9.2 -> Reference Manual -> Special Commands 一节

命令的分类

special commands 这个词语, 官方手册又是没给定义就直接用了, 看了一圈下来, 感觉这个词指的就是所有的命令, 一点也不 special, 估计是出于称呼的必要, 就随便起了个名叫 special commands 吧. 在 special commands 中有一个子集, 叫做 structural commands, 这类命令已经在前面的文章里介绍过了.

从概念上来讲, 目前我遇到的 doxgen 命令只有这两类.

命令的格式

所有命令都以反斜线 \ 或 at 号 @ 开头, 两种写法是完全等价的, 用哪一种都行. 有的命令可以接受参数. 在命令功能的说明中, 采用如下格式约定:

• <尖> 括号表示参数是单个的单词;
• (圆) 括号表示参数一直延续到命令所在行的结尾(中间可以有空格);
• {花} 括号有两种含义:
  • 表示参数一直延续到下一个段落, 段落之间用空行或 section indicator 分隔.
  • 作为命令选项的一部分 (used for command options), 此时这对花括号是正常的字符, 不能省略, 且左花括号必须紧贴命令, 中间不允许有空格.
• [方] 括号表示这个参数是可选(可有可无)的. 但如果方括号放在引号中, 则表示方括号是参数的一部分(可以没有这个参数, 但如果使用这个参数的话, 方括号是参数的一部分, 不能省略).

从上述约定中可以看出, 参数主要是文本, 也就是文档的内容.

常用命令

doxygen 支持非常多的命令, 官方手册提供了一个命令的查询表, 可以查到每一个命令的用法. 先放张图感受一下 doxygen 命令的数量:

上面的命令占了不到半页, 后面还有整整一页的命令. 而实际上我们经常用到的命令只是其中的一小部分. 这符合二八定律, 用户最常用的功能, 只占到了软件提供的所有功能的20%.

下面, 我们来认识一些常用的命令. 除此之外, 网上很多关于 doxygen 的教程, 也主要是介绍这些命令, 读者可以相互补充.

文件注释

以下命令主要用于注释文件:

@file []
@brief {brief description}
@details {detailed description}
@author {list of authors}
@version {version number}
@date {date description}

举例:

/**
@file
@author Tom
@author Jack
@version 1.1.0a
*/

在这里, 我们又看到了 @brief, @details, 实际上, 这里列出的命令, 除了 @file 以外, 也可以用于函数, 结构体等, 而把它们归类为文件注释, 是因为它们通常是和 @file 一起使用的.

需要解释的是, @file 是一个 structural command, 参数 name 是文件名, 也可以是文件的路径, 如果省略了参数(即不填), 则表示其注释的对象是当前文件. 下篇将通过一个例子来进一步解释这一点.

函数注释

下面这些命令主要用于注释函数.

@param

@param '['dir']'  {parameter description}

该命令的第一个参数是函数形参的方向(可选), 取值有[out], [in], 和 [in, out], 方括号不可省略. 第二个参数是函数形参的名字, 第三个参数是函数形参的详细解释. 该命令后面可以同时跟多个函数参数, 例如

/** @brief Sets the position
    @param x,y,z Coordinates of the position in 3D space.
 */
void setPosition(int x, int y, int z, long t);

其他

@bug  {bug description}
@return {description of the return value}
@returns 等价于 @return
@retval  {description}
@note {text}
@attention {attention text}
@warning {warning message}
@exception  {exception description}
@example ['{lineno}'] 

举例:

/// @brief 计算两个整数之和
void add(int &result, int a, int b);

/**
@details 通过指针传出计算结果, 参数的顺序为输出在前, 输入在后;
@param [out] result 和
@param [in]  a, b    被加数
@return 错误原因
    @retval 0   计算成功
    @retval -1  计算结果溢出
    @retval -2  未知错误
@note 和一般习惯不同, 该函数的结果是通过参数传出, 而不是通过返回值给出.
@attention 使用这个函数的时候要格外小心.
@bug 不知道为什么这个函数会导致程序异常退出.
@warning 这个函数其实完全没用, 不要用在产品里, 否则后果自负.
@exception 无 C语言没有 exception 的概念
*/
int add(int &result, int a, int b) 
{}

上面的注释输出成网页是这个样子的: