转: https://www.cnblogs.com/fkpj/p/4537145.html
这个例子以C语言为例,其他的语言类似。
注:文档注释的部分是以/**开始,*/结束。
近段时间,一直在学习华为C语言编程规范(2011版),在“注释”这一章中发现了一种“Doxygen”的注释转文档工具,查看诸多相关资料,并进行编程实践,终于可以利用Doxygen给C程序生成注释文档。在使用过程中,我已经深深地喜欢Doxygen,并在写代码时使用Javadoc注释风格。
本文由三部分组成:1)工具下载及安装;2)编写Doxygen可识别的注释;3)利用Doxygen工具将注释转换成API文档。
1、工具下载及安装
(1)Doxygen可以从一套源文件开始,生成HTML格式的在线类浏览器。笔者采用的版本是Doxygen1.8.9.1
(2)Microsoft HTML Help Workshop是微软开发,用于本工程创建*.chm文件,笔者上官网下载最新的htmlhelp
(3)Graphviz用于配合doxygen使用,提取函数之间、头文件之间的调用关系,笔者使用的版本是graphviz-2.38.
2、编写Doxygen可识别的注释
(1)注释模板
本文采用的是Javadoc风格的注释,参照CSDN博客上的注释模板;
一、文件注释
/**
* @file CommonType.h
* @brief 常见类型定义
* @author Vincent
* @date 2015-5-24
* @version A001
* @copyright Vincent
*/
二、函数注释
/**
* 读取文件
* @param[in] fileNameLen 文件名长度
* @param[in] fileName 文件名
* @param[in] dataLen 数据长度
* @param[out] fileData 输出数据
* @return 0,执行成功,非0,失败,详见
* @ref RetCode.h
* @see
* @note
*/
UINT ReadFile(UINT fileNameLen, BYTE *fileName, UINT dataLen, BYTE *fileData);
三、类型/宏定义注释
/**
* 2字节字符类型
*/
typedef unsigned short WORD;
四、枚举/结构注释
/** 枚举类型*/
enum COLOR{
RED=0, ///< 红色
GREEN=1,///< 绿色
YELLOW=2///< 黄色
};
(2)Doxygen工程实例
为了让接触Doxygen工具的人快速上手,笔者使用VC++6.0创建了一个DoxygenTest工程,并为其编写测试代码以及Javadoc风格的注释,工程的文件列表如下图所示,并依次展示每个文件的代码。
AddrDefine.h
View Code
CommonType.h
View Code
RetCode.h
View Code
DoxygenFile.h
View Code
DoxygenFile.c
View Code
HandleFile.h
View Code
HandleFile.c
View Code
main.c
View Code
3、利用Doxygen工具将注释转换成API文档
接下来,就是利用Doxygen工具将DoxygenTest工程中注释提取出来,转换成chm格式的API文档。第三部分分成九步:1、工程配置;2、模式配置;3、输出配置;4、调用图配置;5、字符集配置;6、输入字符集配置;7、chm配置;8、Grapviz配置;9、执行Doxygen。
1、工程配置;
2、模式配置;
3、输出配置;
4、调用图配置;
5、字符集配置;
6、输入字符集配置;
7、chm配置;
8、Grapviz配置;
9、执行Doxygen
完成上述操作之后,就能生成如下API文档
参考资料
1、Doxygen配置以及注释详细说明文档:doxygen_manual-1.8.9.1.pdf