Doxygen 介绍

​ Doxygen 是一个用于生成文档的工具，主要用于 C++、C、Objective-C、C# 和其他类似语言的代码。它可以根据代码中的注释生成各种格式的文档，包括 HTML、LaTeX、RTF 等。Doxygen 支持多种注释风格，支持 JavaDoc 和 Qt 风格的注释。

​ 通过在代码中添加特定格式的注释，如函数说明、参数说明、返回值说明等，Doxygen 可以根据这些注释生成易于阅读的文档，帮助开发人员更好地理解代码的结构和功能。它还可以生成调用图、继承图等可视化工具，帮助开发人员更好地理解代码之间的关系。

​ Doxygen 是一个功能强大且灵活的工具，广泛用于各种开源项目和商业项目中，帮助开发团队更好地管理和维护其代码库。

  1. Doxygen的安装（通常只需要一台电脑安装进行文档的生成）
  2. Doxygen官方文档

特定注释风格

这里介绍JavaDoc注释格式。写代码时应遵循以下特定格式进行注释。

JavaDoc注释格式

JavaDoc 注释块以 /** 开始，以 */ 结束，通常位于类、方法、字段、构造函数等的前面。以下是常用的 JavaDoc 标签及其说明：

  1. @param: 描述方法参数
  2. @return: 描述方法的返回值
  3. @throws 或 @exception: 描述方法可能抛出的异常
  4. @see: 参考其他相关的类或方法
  5. @deprecated: 标记不推荐使用的方法或类
  6. @since: 指出类或方法在何时被引入
  7. @author: 说明作者信息
  8. @version: 说明版本信息

1. 类的注释

描述类的目的、功能和使用方法。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
/**
 * @class Calculator
 * @brief 提供基本的数学运算功能。
 * 
 * 这个类包含用于基本数学运算的方法，如加法、减法、乘法和除法。
 * 可以用来进行简单的计算。
 * 
 * @see MathUtils
 */
class Calculator {
public:
    /**
     * @brief 计算两个整数的和。
     * 
     * @param a 第一个整数。
     * @param b 第二个整数。
     * @return 两个整数的和。
     * @throws std::invalid_argument 如果任意参数不是有效的整数。
     * @see subtract
     */
    int add(int a, int b);

    /**
     * @brief 计算两个整数的差。
     * 
     * @param a 被减数。
     * @param b 减数。
     * @return 两个整数的差。
     * @see add
     */
    int subtract(int a, int b);
};

2. 函数的注释

详细描述函数的功能、参数、返回值和异常。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
/**
 * @brief 计算两个浮点数的商。
 * 
 * 这个函数接受两个浮点数作为参数，返回它们的商。如果除数为零，则抛出异常。
 * 
 * @param numerator 被除数。
 * @param denominator 除数。
 * @return 两个浮点数的商。
 * @throws std::invalid_argument 如果除数为零。
 * @see multiply
 */
double divide(double numerator, double denominator) {
    if (denominator == 0) {
        throw std::invalid_argument("除数不能为零");
    }
    return numerator / denominator;
}

3. 构造函数的注释

描述类的构造函数及其参数。

1
2
3
4
5
6
7
8
/**
 * @brief 构造一个 Calculator 对象。
 * 
 * 创建一个 Calculator 对象，初始化一些内部状态（如果有的话）。
 * 
 * @param initial_value 初始值（如果有默认值）。
 */
Calculator(double initial_value = 0.0);

4. 变量的注释

说明类成员变量的用途。

1
2
3
4
5
6
7
/**
 * @var double initial_value
 * @brief 初始值。
 * 
 * 这个变量保存计算器的初始值。在创建对象时可以指定它。
 */
double initial_value;

也可以直接简便注释。

1
int var; ///< Brief description after the member

5. 构造函数的注释

注释中描述如何创建类的实例。

1
2
3
4
5
6
/**
 * @brief 默认构造函数。
 * 
 * 默认构造函数会创建一个 Calculator 对象并将初始值设置为 0。
 */
Calculator() : initial_value(0) {}

6. 描述异常情况

说明函数在什么情况下会抛出异常。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/**
 * @brief 计算两个整数的商。
 * 
 * 这个函数接受两个整数作为参数，返回它们的商。如果除数为零，则抛出 std::invalid_argument 异常。
 * 
 * @param numerator 被除数。
 * @param denominator 除数。
 * @return 两个整数的商。
 * @throws std::invalid_argument 如果除数为零。
 */
int divide(int numerator, int denominator) {
    if (denominator == 0) {
        throw std::invalid_argument("除数不能为零");
    }
    return numerator / denominator;
}

7. 使用 @see 标签

引用相关的类、函数或文件。

1
2
3
4
5
6
7
8
9
10
11
12
13
/**
 * @brief 计算两个浮点数的乘积。
 * 
 * 这个函数接受两个浮点数作为参数，返回它们的乘积。
 * 
 * @param a 第一个浮点数。
 * @param b 第二个浮点数。
 * @return 两个浮点数的乘积。
 * @see divide
 */
double multiply(double a, double b) {
    return a * b;
}

8. @deprecated 标签

标记不推荐使用的函数或类。

1
2
3
4
5
6
7
8
9
10
11
/**
 * @deprecated
 * 
 * 这个函数不再推荐使用，请使用新的 add 方法。
 * 
 * @brief 计算两个整数的和。
 * @param a 第一个整数。
 * @param b 第二个整数。
 * @return 两个整数的和。
 */
int oldAdd(int a, int b);

9. @note 标签

添加附加说明或注意事项。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
/**
 * @brief 计算平方根。
 * 
 * 这个函数计算给定非负数的平方根。
 * 
 * @param value 输入值，必须是非负数。
 * @return 输入值的平方根。
 * @note 如果输入值是负数，将抛出 std::invalid_argument 异常。
 */
double sqrt(double value) {
    if (value < 0) {
        throw std::invalid_argument("输入值不能是负数");
    }
    return std::sqrt(value);
}

10. @since 标签

指定自哪个版本开始引入某个功能。

1
2
3
4
5
6
7
8
9
10
11
/**
 * @brief 设置计算器的初始值。
 * 
 * 这个方法设置计算器的初始值，可以在对象创建时或之后调用。
 * 
 * @param value 初始值。
 * @since 1.2.0
 */
void setInitialValue(double value) {
    initial_value = value;
}

文档生成

准备工作

  1. Doxyfile

可以使用命令生成标准模板，也可以使用已有的文件修改。

1
doxygen -g

这里也可以使用其他主题的样式，实现更好看的风格，推荐一个Doxygen Awesome

放入css文件并在配置文件里使用即可。

生成文档

配置好配置文件后可以直接在Doxyfile目录下运行命令生成

1
doxygen

该封面图片由Kevin Seibel在Pixabay上发布