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博客上的注释模板;

  一、文件注释

按 Ctrl+C 复制代码
按 Ctrl+C 复制代码

 

 

  二、函数注释

复制代码
/** 
 * 读取文件
 * @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风格的注释,工程的文件列表如下图所示,并依次展示每个文件的代码。

c++代码文档化注释_第1张图片

 

 

  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

复制代码
View Code

 

  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

复制代码
View Code

 

  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

复制代码
View Code

 

  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

复制代码
View Code

 

  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;
    }
复制代码
View Code

 

  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
复制代码
View Code

 

  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;
    }
复制代码
View Code

 

  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);
}

复制代码
View Code

 

  3、利用Doxygen工具将注释转换成API文档

  接下来,就是利用Doxygen工具将DoxygenTest工程中注释提取出来,转换成chm格式的API文档。第三部分分成九步:1、工程配置;2、模式配置;3、输出配置;4、调用图配置;5、字符集配置;6、输入字符集配置;7、chm配置;8、Grapviz配置;9、执行Doxygen。

  1、工程配置;

  c++代码文档化注释_第2张图片

  2、模式配置;

  c++代码文档化注释_第3张图片

  3、输出配置;

  c++代码文档化注释_第4张图片

  4、调用图配置;

  c++代码文档化注释_第5张图片

  5、字符集配置;

  c++代码文档化注释_第6张图片

  6、输入字符集配置;

  c++代码文档化注释_第7张图片

  7、chm配置;

  c++代码文档化注释_第8张图片

  8、Grapviz配置;

  c++代码文档化注释_第9张图片

  9、执行Doxygen

  c++代码文档化注释_第10张图片

  

  完成上述操作之后,就能生成如下API文档

  c++代码文档化注释_第11张图片

  参考资料

  1、Doxygen配置以及注释详细说明文档:doxygen_manual-1.8.9.1.pdf

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

  3、使用doxygen生成chm范例

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

  5、Doxygen使用简介

你可能感兴趣的:(#,C/C++,c++,注释,doxygen)