Doxygen给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=,    ///<  红色
    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=,    ///<  红色
    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(,NULL,,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(,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

　　2、C++ 程序文档生成器介绍(doxygen)

　　3、使用doxygen生成chm范例

　　4、嵌入式C语言中的Doxygen注释模板

　　5、Doxygen使用简介