为代码生成一个良好可读的API文档-Doxygen简单实战

需求？为什么要有API文档

1. 在代码开发过程中，我们会发现有这样的情况，其他团队的代码和自己团队的代码相异甚大，如果没有一个统一规范的文档来对接，会造成很多交流沟通上的不便，但我们又不想浪费时间去边写说明书边写代码，并且万一哪一天代码需要改动，对应说明书也要改动，这是任何人都及其不愿看到的。
2. 即使在自己团队，也会出现任务较为独立的情况，对于测试人员或者其他开发人员来说，他并不愿意看你写的代码，只想知道怎么使用它，有了API文档，会更方便其他人员查询使用，同时也能为未来项目的完整性提供有力的支持，比如编写成库、后续第三方使用、对外开放介绍之类的可能性。

Doxygen 常用规范及帮助

下面列举了我认为最常使用的一些Doxygen编写规范。
常用注释类型：

1.文件注释

/**
 1. @file 文件名
 2. @brief 简介
 3. @details 细节
 4. @author 作者
 5. @version 版本号
 6. @date 年-月-日
 7. @copyright 版权
 */

2.结构体注释

/**
 * @brief 类的详细描述
 */

3. 函数注释

/**
  * @brief 函数描述
  * @param 参数描述
  * @return 返回描述
  * @retval 返回值描述
  */

4.常量/变量注释

//定义一个整型变量a
int a;

/**
 * @brief 定义一个整型变量a
*/
int a;

int a; /*!< 定义一个整型变量a */
int a; /**< 定义一个整型变量a */
int a; //!< 定义一个整型变量a
int a; ///< 定义一个整型变量a

qt中编写c++代码实践

首先我们创建了一个widget工程，其中包含了三个文件：

然后我们对文件进行文件注释：

结构体注释：

函数注释：


然后使用doxygen编译这个文件夹，具体怎么使用网上有很多教程，这里不在赘述。
编译完成后，打开index.html:可以看到如下界面，首页中包含了编写的文件信息主页，文件列表，和其中包含的类（这里顺便写了一个person类，用student类继承它，测试下效果非常棒，甚至将类的继承关系完美展现出来了）：

然后看下我们的函数注释效果：

Student类的API文档效果：

总结

在使用Doxygen来生成代码API文档时，对注释的编写规范很重要，如果注释写得一塌糊涂，生成的API文档也会不堪入目。总的来说，个人觉得这是个非常不错的API文档生成工具，未来也会更加深入地使用它，更重要的是，它可以使你在编写代码的适合更加注意自己的规范行为，早期使用可能会觉得很繁琐，但坚持下来一定能很大程度上提高你的代码水平。愿一同共勉！