doxygen代码文档

2017-10-03 | 阅读：次

导入

上篇博客讲到了项目如何发布，虽然隔了好久，还是想讲一下doxygen。doxygen是一个代码文档生成工具，根据特定的注释语法自动生成。相信读者都看过很多的开源项目的API文档，doxygen就可以生成这种在线文档效果，通过浏览器查看，也可以用是LaTeX格式。这是跟项目发布息息相关的，项目发布，尤其是闭源项目的话，API文档是开发者了解项目的最重要途径，因此必须清晰且完善。而对于开源项目，重要性也是一样得，很多开发者发布的开源项目，就一个简单README.md,其他没有任何的文档，让使用者很是头疼，还需要慢慢看代码才行。

API文档只是暴露API函数，不暴露内部函数，因此doxygen是可以选择你想暴露的函数的，如果完全暴露，此时代码文档就相当于一个清晰的代码阅读器，每个文件包含哪些类，包含哪些函数，位于源代码多少行，参数返回值作用，异常值等情况，让读者看代码更加高效。

简单语法

doxygen整体是非常简单的，主要还是知不知道使用，详细的语法可以去官网查看，这里简单的说明几个关键语法：

文件注释：在每个文件的开头，使用 /*! 或 /** 开始一个文档块，描述文件的总体信息，包括作者、日期、文件描述等

  /*!
 * @file   example.cpp
 * @brief  这里是对本文件的简要描述
 * @author Your Name
 * @date   YYYY-MM-DD
 */

类和结构体注释：在每个类或结构体声明之前，使用 /*! 或 /** 开始一个文档块，描述该类或结构体的用途、属性等

  /**
 * @class   ExampleClass
 * @brief   这里是类的简要描述
 *
 * 更详细的描述可以放在这里，包括类的用途、注意事项等。
 *
 * @author Your Name
 * @date   YYYY-MM-DD
 */
class ExampleClass {
    // ...
};

函数注释：在每个函数声明或定义之前，使用 /*! 或 /** 开始一个文档块，描述函数的功能、参数、返回值等,常见还有@node 和 @excpetion表示注解和异常。

  /**
 * @brief   函数的简要描述
 * @param   param1 描述参数1
 * @param   param2 描述参数2
 * @return  描述返回值
 */
int exampleFunction(int param1, int param2) {
    // ...
}

代码段：@code … @endcode 用于在文档中插入代码段，保持原始格式

  /**
 * @par	示例代码：
 * @code{.cpp}
 * int main() {
 *     return 0;
 * }
 * @endcode
 */

TODO和 FIXME：在代码中使用 @todo 和 @fixme 标记未完成的任务或需要修复的问题

  /**
 * @todo 实现这个函数
 */
void unfinishedFunction() {
    // ...
}

编号列表：使用 -# 来创建编号列表

  /**
 * 操作步骤：
 * -# 第一步
 * -# 第二步
 * -# 第三步
 */

创建链接：@link … @endlink 用于创建指向文档内部或外部资源的链接

  /**
 * 更多信息请参见 @link http://www.example.com 这里 @endlink。
 */

例子

/**
 * @file example.cpp
 * @brief 一个简单的数学运算示例程序
 * @author cryer
 * @date 2017-10-3
 */

#include <iostream>
#include <cmath>

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

/**
 * @brief 计算两个数的差
 * @param a 被减数
 * @param b 减数
 * @return 两个数的差
 */
double subtract(double a, double b) {
    return a - b;
}

/**
 * @brief 计算平方根
 * @param x 需要计算平方根的数
 * @return 平方根值
 * @note 如果x为负数，将返回NaN
 */
double squareRoot(double x) {
    return sqrt(x);
}

/**
 * @brief MathOperations类提供基本数学运算
 */
class MathOperations {
public:
    /**
     * @brief 计算两个数的乘积
     * @param a 第一个因数
     * @param b 第二个因数
     * @return 两个数的乘积
     */
    double multiply(double a, double b) {
        return a * b;
    }

    /**
     * @brief 计算两个数的商
     * @param a 被除数
     * @param b 除数
     * @return 两个数的商
     * @exception std::invalid_argument 当除数为0时抛出
     */
    double divide(double a, double b) {
        if (b == 0) {
            throw std::invalid_argument("除数不能为0");
        }
        return a / b;
    }
};

/**
 * @brief 程序入口点
 * @param argc 命令行参数个数
 * @param argv 命令行参数数组
 * @return 程序退出状态码
 */
int main(int argc, char* argv[]) {
    MathOperations math;
    
    std::cout << "5 + 3 = " << add(5, 3) << std::endl;
    std::cout << "5 - 3 = " << subtract(5, 3) << std::endl;
    std::cout << "5 * 3 = " << math.multiply(5, 3) << std::endl;
    
    try {
        std::cout << "5 / 3 = " << math.divide(5, 3) << std::endl;
        std::cout << "5 / 0 = " << math.divide(5, 0) << std::endl;
    } catch (const std::exception& e) {
        std::cerr << "错误: " << e.what() << std::endl;
    }
    
    std::cout << "√25 = " << squareRoot(25) << std::endl;
    
    return 0;
}