Doxygen的使用-用于生成代码文档的工具

Doxygen的使用-用于生成代码文档的工具

一、CMakeLists使用

二、Doxygen的使用-用于生成代码文档的工具

三、ubuntu16.04 VSCode下cmake+clang+lldb调试c++

四、Git使用教程-分支使用/合并分支提交

---

---

Doxygen 是一个用于从源代码中提取注释并生成文档的工具，支持多种编程语言（如 C++、C、Java、Python 等）。
通过 Doxygen，可以轻松为代码生成高质量的文档，提升项目的可维护性和可读性。
c++ Doxygen注释语法

2.1 安装 Doxygen

Linux：

sudo apt-get install doxygen 

2.2 常用 Doxygen 标签

以下是一些常用的 Doxygen 标签：

@class 类名
@struct 结构体名
@brief：简要描述。
@param：函数参数。
@return：函数返回值。
@file：文件描述。
@class：类描述。
@see：参考其他内容。
@note：注意事项。
@warning：警告信息。

2.3 编写 Doxygen 注释

在代码中编写 Doxygen 风格的注释。以下是一些常见的注释格式：

2.3.1 文件注释

/**  
 * @file example.cpp  
 * @brief 这是一个示例文件  
 */  
 
 /**  
 * @file    Calculator.h  
 * @brief   实现科学计算器核心逻辑  
 * @author  Zhang San (zhangsan@example.com)  
 * @date    2025-03-28  
 * @version 2.1.0  
 * @license Apache 2.0  
 */  

2.3.2 函数注释

/**  
 * @brief 计算两个数的和  
 * @param a 第一个数  
 * @param b 第二个数  
 * @return 两个数的和  
 */  
int add(int a, int b) {  
    return a + b;  
}  

2.3.3 类/结构体注释

/**  
 * @brief 这是一个示例类  
 */  
class Example {  
public:  
    /**  
     * @brief 构造函数  
     */  
    Example();  
  
    /**  
     * @brief 打印消息  
     * @param msg 要打印的消息  
     */  
    void print(const std::string& msg);  
}; 

/**  
 * @class   Matrix  
 * @brief   表示数学中的矩阵结构，支持基本线性代数运算  
 *  
 * @details 本类使用行优先存储策略，支持以下操作：  
 *          - 矩阵加减法  
 *          - 矩阵乘法  
 *          - 求逆矩阵（仅限方阵）  
 *   
 * @tparam T 矩阵元素类型（需支持算术运算）  
 * @ingroup MathUtils  
 */   

2.4 配置 Doxygen

Doxygen 需要一个配置文件（Doxyfile）来指定生成文档的选项。

2.4.1 生成配置文件

在项目根目录下运行以下命令生成默认配置文件：

doxygen -g Doxyfile  

2.4.2 编辑配置文件

打开生成的 Doxyfile 文件，根据需要修改以下常用选项：

PROJECT_NAME：项目名称。
OUTPUT_DIRECTORY：输出目录。
INPUT：源代码目录。
RECURSIVE：是否递归搜索子目录。
EXTRACT_ALL：是否提取所有代码的文档。
GENERATE_HTML：是否生成 HTML 文档。
GENERATE_LATEX：是否生成 LaTeX 文档。

例如：

PROJECT_NAME           = "My Project"  
OUTPUT_DIRECTORY       = ./docs  
INPUT                  = ./src  
RECURSIVE              = YES  
EXTRACT_ALL            = YES  
GENERATE_HTML          = YES  
GENERATE_LATEX         = NO 

2.5 生成文档

在项目根目录下运行以下命令生成文档：

doxygen Doxyfile  

生成的文档会保存在 OUTPUT_DIRECTORY 指定的目录中（如 ./docs）。

2.6 查看文档

HTML 文档：打开 ./docs/html/index.html 文件，可以在浏览器中查看生成的文档。
LaTeX 文档：如果生成了 LaTeX 文档，可以进入 ./docs/latex 目录，运行 make 生成 PDF 文件。

2.7 使用 Doxywizard（可选）

Doxywizard 是 Doxygen 的图形化配置工具，适合不熟悉命令行操作的用户。
打开 Doxywizard。
加载 Doxyfile 配置文件。
修改配置并生成文档。

2.8 示例项目

以下是一个简单的示例项目结构：

my_project/  
├── Doxyfile  
├── src/  
│   ├── example.cpp  
│   └── example.h  
└── docs/ (生成的文档)  

example.h

/**  
 * @file example.h  
 * @brief 示例头文件  
 */  
  
/**  
 * @brief 示例类  
 */  
class Example {  
public:  
    /**  
     * @brief 打印消息  
     * @param msg 要打印的消息  
     */  
    void print(const std::string& msg);  
};  

example.cpp

#include "example.h"  
#include <iostream>  
  
void Example::print(const std::string& msg) {  
    std::cout << msg << std::endl;  
} 

生成文档

doxygen Doxyfile