需求？为什么要有API文档
- 在代码开发过程中，我们会发现有这样的情况，其他团队的代码和自己团队的代码相异甚大，如果没有一个统一规范的文档来对接，会造成很多交流沟通上的不便，但我们又不想浪费时间去边写说明书边写代码，并且万一哪一天代码需要改动，对应说明书也要改动，这是任何人都及其不愿看到的。
- 即使在自己团队，也会出现任务较为独立的情况，对于测试人员或者其他开发人员来说，他并不愿意看你写的代码，只想知道怎么使用它，有了API文档，会更方便其他人员查询使用，同时也能为未来项目的完整性提供有力的支持，比如编写成库、后续第三方使用、对外开放介绍之类的可能性。
Doxygen 常用规范及帮助
下面列举了我认为最常使用的一些Doxygen编写规范。
常用注释类型：
1.文件注释
/**
1. @file 文件名
2. @brief 简介
3. @details 细节
4. @author 作者
5. @version 版本号
6. @date 年-月-日
7. @copyright 版权
*/
2.结构体注释
/**
* @brief 类的详细描述
*/
- 函数注释
/**
* @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文档生成工具，未来也会更加深入地使用它，更重要的是，它可以使你在编写代码的适合更加注意自己的规范行为，早期使用可能会觉得很繁琐，但坚持下来一定能很大程度上提高你的代码水平。愿一同共勉！
