c++代码文档化注释

最新推荐文章于 2023-05-22 09:30:49 发布
最新推荐文章于 2023-05-22 09:30:49 发布
阅读量5.6k 收藏 7
点赞数 1
分类专栏： # C/C++ 文章标签： c++ 注释 doxygen

　　 近段时间，一直在学习华为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风格的注释，工程的文件列表如下图所示，并依次展示每个文件的代码。

 

 

　　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、工程配置；

　　

　　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使用简介

zpethan
关注
  • 1
    点赞
  • 踩
  • 7
    收藏
    觉得还不错? 一键收藏
  • 2
    评论
专栏目录
C++学习笔记-注释
cuihwchn的博客
02-16 274
C++学习笔记-注释
c++ API中文文档
11-08
中文C++介绍文档，里面包括基本最常用的库函数以及使用介绍，再也慢慢看英文啦
Doxygen给C程序生成注释文档
weixin_33895657的博客
05-28 820
　　 近段时间，一直在学习华为C语言编程规范（2011版），在“注释”这一章中发现了一种“Doxygen”的注释转文档工具，查看诸多相关资料，并进行编程实践，终于可以利用Doxygen给C程序生成注释文档。在使用过程中，我已经深深地喜欢Doxygen，并在写代码时使用Javadoc注释风格。 　　本文由三部分组成：1）工具下载及安装；2）编写Doxygen可识别的注释；3）利用Doxygen工具...
C语言大纲
weixin_64499720的博客
04-17 733
数据类型 运算符，表达式和语句 循环 分支与跳转 函数 数组 结构体，联合体 指针 宏定义 1-数据类型
【C/C++ 基本知识 注释规范】C/C++中注释方式以及规范
探索C++编程的奥秘，分享深入的技术见解和实践，旨在激发读者创造力与解决问题的思维。
07-04 5035
注释是编译器忽略但对于程序员非常有用的文本。 注释通常用于批注代码以供将来参考。 在C/C++中，使用注释有三种方法。
【C++学习第十讲】C++ 注释
wzk4869的博客
05-22 2505
【C++学习第十讲】C++ 注释
C++代码文档生成器 根据代码及注释自动生成代码文档.zip
01-30
C++代码文档生成器 根据代码及注释自动生成代码文档.zip
vscode使用官方C/C++插件无法进行代码格式化问题
12-20
官方的C/C++插件是支持使用.clang-format配置文件进行自定义风格代码格式化的，无需另外安装clang-format插件。 但是使用clang-format -style=llvm -dump-config > .clang-format导出的默认配置文件进行格式化的时候...
基于B+树数据库的图书管理系统c++源码+详细注释+详细说明文档.zip
最新发布
04-11
基于B+树数据库的图书管理系统c++源码+详细注释+详细说明文档.zip 基于B+树数据库的图书管理系统c++源码+详细注释+详细说明文档.zip 基于B+树数据库的图书管理系统c++源码+详细注释+详细说明文档.zip 基于B+树数据库...
C++实现mqtt 的数据收发，代码进行了注释说明，增加CMakelist编译, 新增文档说明
08-31
C++实现mqtt 的数据收发，代码进行了注释说明，pdf文档介绍了MQTT服务器搭建流程 和 mqtt库安装流程，增加CMakeLists.txt 编译,readme.txt 记录各个cpp 的功能与差异，方面快速入门
c/c++ API chm c/c++函数库
05-03
c/c++ API 主要是c/c++函数 c/c++ API 主要是c/c++函数 c/c++ API 主要是c/c++函数 c/c++ API 主要是c/c++函数 c/c++ API 主要是c/c++函数 c/c++ API 主要是c/c++函数 C++ API chm C++ API chm C++ API chm C++ API chm C++ API chm C++ API chm
c++api.chm
12-30
c++ STL类库的所有的类，C函数库，C++string等c++开发用到的类和函数，chm格式和javaAPI形式一样
C++导引头模型仿真代码(注释丰富)
03-15
Seekers导引头模型仿真C++源码；内含Seeker仿真模块、导引头电机环节、导引头PID环节等。编写：替补哥。代码注释丰富。导引头模型说明请参见源码内文档。 运行环境：Windows/Visual C/C++
C++API文档
我写写哈的博客
11-26 2148
C++API文档（免费版） 链接：https://pan.baidu.com/s/13_0aRFAsllQXqEenvztEmA 提取码：ktop
C++API 中文文档
网瘾少年丶的博客
06-05 1001
https://www.apiref.com/cpp-zh/cpp/concepts.html
c、c++ 常用API汇总
baiiu
04-15 9893
前言 本文汇总c、cpp里常用API，会持续更新，便于查阅。 <string.h> char *strchr(const char *str, int c) 在参数 str 所指向的字符串中搜索第一次出现字符 c（一个无符号字符）的位置。 char *strstr(const char *haystack, const char *needle) 在字符串 haystack 中查找第一次出现字符串 needle 的位置，不包含终止符 ‘\0’； 返回字符串str中第一次出现子串subst
C++ API.chm
weixin_34162629的博客
06-14 502
本文将帮助您迅速了解 C++ 中服务数据对象的基本应用程序编程接口（Application Programming Interface，API）。告诉你一些函数和用法，我是从别处下载的，希望对大家有帮助！ 转载于:https://blog.51cto.com/localhost/332512...
C++ 注释【菜鸟教程】
sixstar666的博客
04-28 6797
程序的注释是解释性语句，您可以在 C++ 代码中包含注释，这将提高源代码的可读性。所有的编程语言都允许某种形式的注释。 C++ 支持单行注释和多行注释。注释中的所有字符会被 C++ 编译器忽略。 C++ 注释一般有两种： //- 一般用于单行注释。 /* ... */- 一般用于多行注释。 注释以//开始，直到行末为止。例如： #include <iostream> using namespace std; int main() { // 这是一个注释...
《C++》API文档（二）
m0_57037805的博客
10-05 1256
《C++》API文档（二），C++基础知识点整理。
C++ 文件代码注释
07-27
当编写C++代码时，注释是非常重要的。它们有助于提高代码的可读性和可维护性，并使其他开发人员更容易理解你的意图。在C++中，有两种主要的注释方式：单行注释和多行注释。 1. 单行注释：使用双斜杠（//）来注释一行代码。例如： ```cpp int x = 5; // 这是一个变量的声明 ``` 2. 多行注释：使用斜杠和星号（/* ... */）来注释多行代码。例如： ```cpp /* 这是一个多行注释的示例。 这里可以写更多的注释内容。 */ ``` 除了这两种常见的注释方式外，还有一种特殊的注释方式是文档注释，用于生成代码文档。文档注释以双斜杠和两个星号（///）开头，通常用于描述函数、类和成员变量等。例如： ```cpp /// 这是一个计算圆面积的函数 /// @param radius 圆的半径 /// @return 圆的面积 double calculateArea(double radius) { return 3.14 * radius * radius; } ``` 通过使用适当的注释，你可以提高代码的可读性和可维护性，并使其他人更容易理解你的代码意图。记住，在编写注释时要保持简洁明了，并遵循良好的编码规范。

“相关推荐”对你有帮助么？

  • 非常没帮助
  • 没帮助
  • 一般
  • 有帮助
  • 非常有帮助
提交
评论 2
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值