近段时间，一直在学习华为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
/** * @file AddrDefine.h * @brief 地址定义 */ #ifndef ADDR_DEFINE_H #define ADDR_DEFINE_H /**@name 地址定义 * @{ */ #define ADDR_FILE_START 0x00000000 ///<文件起始地址 #define ADDR_DIR_START 0x00000001 ///<目录起始地址 /**@} */ #endif
CommonType.h
/** * @file CommonType.h * @brief 常见类型定义 * @author Vincent * @date 2015-5-24 * @version A001 * @copyright Vincent */ #ifndef COMMON_TYPE_H #define COMMON_TYPE_H /** * 4字节字符类型 */ typedef unsigned int UINT; /** * 1字节字符类型 */ typedef unsigned char BYTE; /** * 2字节字符类型 */ typedef unsigned short WORD; /** 坐标系类型 */ typedef struct{ int x;///<横坐标 int y;///<纵坐标 }Coordinator; /** 枚举类型*/ enum COLOR{ RED=0, ///< 红色 GREEN=1,///< 绿色 YELLOW=2///< 黄色 }; /** 空的宏定义*/ #define NULL 0 #endif
RetCode.h
/** * @file RetCode.h * @brief 错误码返回值 * @author Vincent * @date 2015-5-24 * @version A001 * @par Copyright (c): Vincent */ #ifndef RET_CODE_H #define RET_CODE_H /**@name 执行状态 * @{ */ #define SUCCESS 0x00000000 ///<执行成功 #define ERR_PARA_LEN 0x00000001 ///<长度错误 #define ERR_NULL_POINT 0x00000002 ///<空指针错误 #define ERR_PARA_TYPE 0x00000003 ///<参数类型错误 /** @}*/ #endif
DoxygenFile.h
/** * @file DoxygenFile.h * @brief 中间层，用于处理数据 * @author Vincent * @date 2015-5-24 * @version A001 * @par Copyright (c): Vincent */ #ifndef DOXYGEN_FILE_H #define DOXYGEN_FILE_H #include "CommonType.h" /** * 写入一些内容 * @param[in] fileNameLen 文件名长度 * @param[in] fileName 文件名 * @param[out] fileData 文件数据 * @return 0，执行成功，非0，失败，详见 * @ref RetCode.h */ int HandleData(UINT fileNameLen,BYTE *fileName, BYTE *fileData); #endif
DoxygenFile.c
#include "DoxygenFile.h" #include "HandleFile.h" /** * 写入一些内容 * @param[in] fileNameLen 文件名长度 * @param[in] fileName 文件名 * @param[out] fileData 文件数据 * @return 0，执行成功，非0，失败，详见 * @ref RetCode.h */ int HandleData(UINT fileNameLen,BYTE *fileName, BYTE *fileData) { UINT retCode; retCode = ReadFile(0,NULL,0,NULL); return retCode; }
HandleFile.h
/** * @file HandleFile.h * @brief 操作文件 * @details 所有涉及文件操作 * @author Vincent * @date 2015-5-24 * @version A001 * @par Copyright (c): Vincent */ #ifndef HANDLE_FILE_H #define HANDLE_FILE_H #include "CommonType.h" /** * 读取文件 * @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); /** * 写入文件 * @param[in] fileNameLen 文件名长度 * @param[in] fileName 文件名 * @param[out] fileData 输出数据 * @return 0，执行成功，非0，失败，详见 * @ref RetCode.h * @see * @note */ UINT WriteFile(UINT fileNameLen, BYTE *fileName, BYTE *fileData); /** * 擦除文件 * @param[in] fileNameLen 文件名长度 * @param[in] fileName 文件名 * @return 0，执行成功，非0，失败，详见 * @ref RetCode.h * @see * @note */ UINT EraseFile(UINT fileNameLen, BYTE *fileName); #endif
HandleFile.c
#include "HandleFile.h" #include "RetCode.h" #include "AddrDefine.h" /** * 读取文件 * @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) { return SUCCESS; } /** * 写入文件 * @param[in] fileNameLen 文件名长度 * @param[in] fileName 文件名 * @param[out] fileData 输出数据 * @return 0，执行成功，非0，失败，详见 * @ref RetCode.h * @see * @note */ UINT WriteFile(UINT fileNameLen, BYTE *fileName, BYTE *fileData) { return SUCCESS; } /** * 擦除文件 * @param[in] fileNameLen 文件名长度 * @param[in] fileName 文件名 * @return 0，执行成功，非0，失败，详见 * @ref RetCode.h * @see * @note */ UINT EraseFile(UINT fileNameLen, BYTE *fileName) { return SUCCESS; }
main.c
#include "DoxygenFile.h" #include "CommonType.h" /** * @mainpage Doxygen工程演示 * @section 介绍 * 1、本工程使用了5个头文件 * @ref AddrDefine.h * @ref CommonType.h * @ref DoxygenFile.h * @ref HandleFile.h * @ref RetCode.h \n * 2、生成本工程，需安装Doxygen、htmlhelp、GraphViz三个软件 */ void main() { HandleData(0,NULL,NULL); }
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
