代码文档生成工具doxdgen使用简易教程

标题代码文档工具简易使用手册

说明：doxygen是一款开源的代码文档生成工具，在简单的探索研究之后，主要用于本项目生成dfs_api.h的接口文档，提供给用户侧查阅接口，按照指定的格式进行注释，使用doxygen工具可以自动生成接口文档，期望大家可以推广使用。以下仅对window下doxygen处理C代码的简易教程
1.doxygen下载安装
下载地址：https://www.doxygen.nl/download.html

在这个页面不用填写邮箱什么的，直接下拉下载，下载后直接安装即可。
2.doxygen配置
打开doxygen如下。
Topics->Project下需要配置的有：工作目录、源文件目录和目的文件目录；项目名称默认为My Project，可以根据需要修改；Scan recursively建议选上，如果所有文件都在源目录下，且没有子文件夹，可以不选；

Topics->Mode配置如下：

Topics->Output使用默认如下，但是如果觉得UI不好看，可以通过change color自己改变

Expert下设置：
Project：

DOXYFIELE_ENCODING,如果不要显示中文，可以用默认的UTF-8，需要显示中文，需要手动输入GB2312，不然会乱码
OUTPUT_LANGUAGE:Chinese
下拉至OPTIMIZE_OUTPUT_FOR_C选项勾选上，输出会更符合C语言风格

Build选项如图

Input选项：
这个选项中INPUT_ENCODING,这个参数很重要，我尝试了几次，按默认的UTF-8成功了，其他的编码选项，我没有测试成功，好像支持UTF-8。输入文件的编码方式必须是UTF-8，这个需要查看自己输入文档的编码格式，一般有中文注释不乱码的都是GB2312，选择保存高级选项，在source insight中是file->save as encoding，选择保存为UTF-8格式。保存之前一定要注意，保留一份原来的副本，不然保存为UTF-8之后，再次打开中文注释会变成乱码。
FILE_PATTERNS：选择输入文档的类型

3.代码注释的格式
注释写在函数的前边，格式如下：

/**
* @brief 函数简要说明
* 函数的详细说明
* @param 传入参数1
* @param 传入参数2
* @param 传入参数3
* @return 返回结果说明
* @retval 返回值说明
*/
//如果是文档说明，可以写在文档开头。
/**
     * @file 本范例的include档案。
     *
     * 这个档案只定义example这个class。
     *
     * @author garylee@localhost
*/

例子如下，每一项都可以自己定义

/**
* @brief 写文件
* 
* @param fd ：文件句柄(：前后都有空格，这样生成比较整齐)
* @param buf ：缓冲区指针
* @param size ：读取的字节数
* @return 成功 – 返回实际写入的字节数    (***需要两个以上的英文空格才能换行***)
*        失败 – 返回-1，errno存放错误码 （***开头空格与成功对齐，转换后才能对齐***）
*        ENOENT：文件/目录不存在; EINVAL：参数错误；EBADF：文件没有被打开、app句柄错误；
*        ENXIO：双磁盘故障；EIO：其它错误，如DFS未完成初始化、设备错误、网络超时
*/
extern ssize_t uss_write(int fd, const void *buf, size_t size, ...);
/**
* @brief 读文件
* 
* @param fd：文件句柄
* @param buf：缓冲区指针
* @param size：读取的字节数
* @return 成功 – 返回实际读取的字节数  
*		 失败 – 返回-1，errno存放错误码
*/
extern ssize_t uss_read(int fd, void *buf, size_t size, ...);

最终生成的是HTML文件，在工作目录的html文件夹下，如下，在浏览器中可以直接打印成PDF文档。