标题代码文档工具简易使用手册
说明: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文档。