C++ 程序文档生成器(doxygen)使用说明

        程序文档,是每个程序员必看文档,在日常业务开发中,难免会封装一些组件。没有很好的组件文档,再好的组件都是废物,。因此大型业务中,文档和思维导图,两个都是必备!
 

一、注释风格
        需要在c/c++代码中按照下面的风格添加注释,基本上还是很顺手的C++的注释风格 主要使用下面这种样式:即在注释块开始使用三个反斜杠‘/’

1.1. 文件注释

/***************************************
* @file 文件名
* @brief 概述
*
* 详细概述
*
* @author 作者,包含email等
* @version 版本号(maj.min,主版本.分版本格式)
* @date 日期
*****************************************/


1.2. 命名空间的注释

///@brief 简单概述
///
///详细概述


1.3. 类定义注释

对需要的类增加注释,需要 说明类的设计方法,类的使用指南,说明类的不变项

///@brief 简要概述
///
///详细说明
///
///使用指南设计函数调用可以@ref 函数名 用于引用其他的说明
///
///其他说明,重写父类函数加以特殊实现
///
///@invariant 类不变项,例如哪些值不会超多少多少
///
class xxx
{…};


1.4. 数据声明注释

行尾说明

Type varName;///< 说明


多行说明

/// 说明
///
///
Type varName;


1.5. 函数注释规范

///@brief 简单概述
///
///详细说明
///@param[in|out] 参数名,in,out表示输入还是输出
///@pre 前者条件
///@return 说明
///@retval 返回值 说明, 这个是可选的
///@post 说明函数完成后的世界状态


1.6. 代码标记数值规范

///@todo 将要做的代码
///@bug 表示此处的bug描述


1.7. 枚举变量的注释示例

///  颜色的枚举定义  
///  
///  该枚举定义了系统中需要用到的颜色\n  
///  可以使用该枚举作为系统中颜色的标识  
enum TEnum  
{  RED,      ///< 枚举,标识红色    BLUE,      ///< 枚举,标志蓝色    YELLOW     ///< 枚举,标志黄色.    
}enumVar;   


附:Doxygen支持的指令

        可以在注释中加一些Doxygen支持的指令,主要作用是控制输出文档的排版格式,使用这些指令时需要在前面加上“\”或者“@”(JavaDoc风格)符号,告诉Doxygen这些是一些特殊的指令,通过加入这些指 令以及配备相应的文字,可以生成更加丰富的文档,下面对比较常用的指令做一下简单介绍。

常用指令介绍

@file    档案 的批注说明。
@author    作者 的信息
@brief    用于class 或function的简易说明eg:@brief 本函数负责打印错 误信息串
@param    主要 用于函数说明中,后面接参数的名字,然后再接关于该参数的说明
@return    描述 该函数的返回值情况eg:@return 本函数返回执 行结果,若成功则返回TRUE,否则返回FLASE
@retval    描述 返回值类型eg:@retval NULL 空字 符串。@retval !NULL 非 空字符串。
@note    注解
@attention    注意
@warning    警告 信息
@enum    引用了某个枚举,Doxygen会在该枚举处产生一个链接eg:@enum CTest::MyEnum
@var    引用了某个变量,Doxygen会在该枚举处产生一个链接eg:@var CTest::m_FileKey
@class    引用 某个类,格式:@class [] []eg:@class CTest “inc/class.h”
@exception    可能 产生的异常描述eg:@exception 本函数 执行可能会产生超出范围的异常


==================

二、 linux下使用doxygen
我的开发环境是ubuntu, 默认有doxygen 命令,如果没有可以从官网下载一个编译安装之doxygen工具的使用简单的2步就够了:

2.1. 生成默认配置文档

doxygen -s -g yourconfigname


这一条命令就可以生成一个叫 “yourconfigname” 的配置文档

接下来需要打开这个文档,对其中某些字段做配置,一般来说,只需要配置其中十几个字段就可以:

\# 项目名称,将作为于所生成的程序文档首页标题
PROJECT_NAME       = “Test“
\# 文档版本号,可对应于项目版本号,譬如 svn 、 cvs 所生成的项目版本号
PROJECT_NUMBER     = "1.0.0”
\# 程序文档输出目录
OUTPUT_DIRECTORY   = doc/
\# 程序文档语言环境
OUTPUT_LANGUAGE   = Chinese
\# 如果是制作 C 程序文档,该选项必须设为 YES ,否则默认生成 C++ 文档格式
OPTIMIZE_OUTPUT_FOR_C  = YES
\# 对于使用 typedef 定义的结构体、枚举、联合等数据类型,只按照 typedef 定义的类型名进行文档化
TYPEDEF_HIDES_STRUCT   = YES
\# 在 C++ 程序文档中,该值可以设置为 NO ,而在 C 程序文档中,由于 C 语言没有所谓的域 / 名字空间这样的概念,所以此处设置为 YES
HIDE_SCOPE_NAMES    = YES
\# 让 doxygen 静悄悄地为你生成文档,只有出现警告或错误时,才在终端输出提示信息
QUIET  = YES
\# 只对头文件中的文档化信息生成程序文档
FILE_PATTERNS     = *.h
\# 递归遍历当前目录的子目录,寻找被文档化的程序源文件
RECURSIVE        = YES
\# 示例程序目录
EXAMPLE_PATH      = example/
\# 示例程序的头文档 (.h 文件 ) 与实现文档 (.c 文件 ) 都作为程序文档化对象
EXAMPLE_PATTERNS    = *.c  *.h
\# 递归遍历示例程序目录的子目录,寻找被文档化的程序源文件
EXAMPLE_RECURSIVE   = YES
\# 允许程序文档中显示本文档化的函数相互调用关系 
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION  = YES
REFERENCES_LINK_SOURCE = YES
\# 不生成 latex 格式的程序文档
GENERATE_LATEX     = NO
\# 在程序文档中允许以图例形式显示函数调用关系,前提是你已经安装了 graphviz 软件包
HAVE_DOT        = YES
CALL_GRAPH      = YES
CALLER_GRAPH    = YES
\# 让 doxygen 从配置文件所在的文件夹开始,递归地搜索所有的子目录及源文件
**RECURSIVE = YES**  
\# 在最后生成的文档中,把所有的源代码包含在其中
**SOURCE BROWSER = YES**
$ 这会在 HTML 文档中,添加一个侧边栏,并以树状结构显示包、类、接口等的关系
**GENERATE TREEVIEW** **=** **ALL**


2.2. 执行命令

doxygen yourconfigname


        这一条命令就可以在指定的目录下生成 html 目录(根据配置决定,也可以生成帮助文档等)

2.3 用apache等存放刚刚生成的html目录

        比如我的机器安装了apache,则可以在 /var/run/www 目录下建一个软连接

连接到刚刚生成好的 html 目录,然后就可以从浏览器访问文档了,下面是我的项目的文档界面

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/629131.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

Google上架:2024年一月政策限制之用户生成的内容

为确保 Google Play 用户能够获得安全、值得信赖的使用体验&#xff0c;Google会定期更新开发者计划政策。今天就来讲解一下关于一月新政策《用户生成的内容》。 目录 公布日期&#xff1a;2023-10-25内容公告相关博客截止时间2024-1-31 公布日期&#xff1a;2023-10-25 内容…

【Java】源码文件开头添加注释

需求 应公司质量部要求&#xff0c;需要对代码做静态检查。质量部要求&#xff0c;源码文件必须在起始行起设置一些注释&#xff0c;然而项目已经开发了一年之久&#xff0c;且没有维护这个注释。 此时&#xff0c;面对好几千个源码文件&#xff0c;我们如何快速添加相应的注…

HTML--基本结构构成

基本结构&#xff1a; 文档声明: <!DOCTYPE html> htm标签对 :<html> </html> head标签对&#xff1a; <head> </head> body标签对&#xff1a;<body> </body> 如下结构&#xff1a; <html> <head> <title>这是一…

Vue-22、总结Vue数据监测

1、功能 <!DOCTYPE html> <html lang"en"> <head><meta charset"UTF-8"><title>Vue总结数据监测</title><script type"text/javascript" src"https://cdn.jsdelivr.net/npm/vue2/dist/vue.js"…

FFmpeg之SWScale

文章目录 一、概述二、函数调用结构图三、Libswscale处理数据流程四、重要结构体4.1、SwsContext4.2、SwsFilter 五、重要函数5.1、sws_getContext5.1.1、sws_alloc_context5.1.2、sws_init_context 5.2、sws_scale5.2.1、SwsContext中的swscale()5.2.2、check_image_pointers5…

电脑技巧:BitLocker是啥,有啥用,看完本文你就懂了

目录 一、 介绍 二、BitLocker用途 三、 工作原理 四、 配置和管理 五、安全性和适用性 六、总结 一、 介绍 BitLocker是由微软开发的全磁盘加密工具&#xff0c;它旨在保护计算机上的数据免受未经授权的访问或窃取。BitLocker通过对整个磁盘进行加密&#xff0c;可以在计…

1、机器学习模型的工作方式

第一步,如果你是机器学习新手。 本课程所需数据集夸克网盘下载链接:https://pan.quark.cn/s/9b4e9a1246b2 提取码:uDzP 文章目录 1、简介2、决策树优化3、继续1、简介 我们将从机器学习模型如何工作以及如何使用它们的概述开始。如果你以前做过统计建模或机器学习,这可能感…

DDOS攻击,一篇文章给你讲清!

1、互联网安全现状 随着网络世界的高速发展&#xff0c;各行业数字化转型也在如火如荼的进行。但由于TCP/IP网络底层的安全性缺陷&#xff0c;钓鱼网站、木马程序、DDoS攻击等层出不穷的恶意攻击和高危漏洞正随时入侵企业的网络&#xff0c;如何保障网络安全成为网络建设中的刚…

【征服redis6】Redis的内存淘汰详解

目录 1.redis的基本策略 2.Redis中的缓存淘汰策略 3.Redis内存不足的情况 4.几种淘汰策略的实现原理 5.项目实践与优化策略 5.1 配置案例 5.2 项目优化策略参考 数据库存储会将数据保存到磁盘中&#xff0c;而Redis的核心数据是在内存中的&#xff0c;而Redis本身主要用来…

安全狗方案入选工信部《2023年工业和信息化领域数据安全典型案例名单》

近日&#xff0c;工业和信息化部网络安全管理局公布了2023年工业和信息化领域数据安全典型案例名单。 安全狗与厦门卫星定位应用股份有限公司、中移 (上海) 信息通信科技有限公司联合申报的智慧交通云数据安全与隐私保障典型案例也成功入选。 厦门服云信息科技有限公司&#…

Vue-24、Vue过滤器

1、效果 2、过滤器实现 <!DOCTYPE html> <html lang"en"> <head><meta charset"UTF-8"><title>过滤器</title><script type"text/javascript" src"https://cdn.jsdelivr.net/npm/vue2/dist/vue.…

OpenCV-Python(45):立体图像中的深度地图

基础 在OpenCV中&#xff0c;深度地图通常是通过计算立体视觉&#xff08;stereo vision&#xff09;或结构光&#xff08;structured light&#xff09;技术得到的。立体视觉是通过将两个或多个摄像机&#xff08;或图像&#xff09;的视角结合起来&#xff0c;计算物体的深度…

Kafka 的架构

实验过程 1.三个虚拟机中解压kafka软件包 tar -zxvf kafka_2.11-1.1.1.tgz 2.修改 3 个节点配置文件 在 zookeeper 节点&#xff0c;进入 kafka_2.11-1.1.1/config 目录下&#xff0c;编辑 server.properties 文件 [rootdb1 ~]# cd kafka_2.11-1.1.1/config [rootdb1 con…

智能路由器 端口映射 (UPnP) Padavan内网端口映射配置方法

新版本Padavan 4.4内核的端口映射配置和老版本的不太一样,因为新版本默认是启用的 UPnP端口映射, 同时默认使用的是 IGD UPnP自动端口映射, UPnP名词解释: UPnP通用即插即用&#xff0c;是一组协议的统称&#xff0c;是一种基于TCP/IP、UDP和HTTP的分布式、开放体系&#xff…

P9847 [ICPC2021 Nanjing R] Crystalfly 题解 (SPJ)

[ICPC2021 Nanjing R] Crystalfly 传送门&#xff1f; 题面翻译 给定一个 n ( 1 ≤ n ≤ 1 0 5 ) n(1\le n\le10^5) n(1≤n≤105) 个节点的树&#xff0c;每个节点上有 a i a_i ai​ 只晶蝶。派蒙最初在 1 1 1 号节点&#xff0c;并获得 1 1 1 号节点的所有晶蝶&#xf…

NetSuite学习笔记 - 中心

一、什么是中心&#xff1f; 对于每个用户&#xff0c;NetSuite 会根据用户的指定角色显示一组可变的标签页面&#xff0c;称为中心。通俗来讲呢&#xff0c;NetSuite的中心其实就是我们常说的“导航菜单”。 只是在我过去常见的系统中&#xff0c;导航菜单一般都是固定的&am…

Elasticsearch Windows部署-ELK技术栈

1、下载Elasticsearch、kibana、logstash 本文不介绍ELK相关原理知识&#xff0c;只记录部署操作过程 下载地址Past Releases of Elastic Stack Software | Elastic 选择同一版本&#xff0c;这里选择是当前最新版本8.11.3 解压放在同目录下&#xff0c;方便后续操作与使用 …

浅入浅出Spring架构设计

浅入浅出Spring架构设计 前言 为什么需要Spring? 什么是Spring? 对于这样的问题&#xff0c;大部分人都是处于一种朦朦胧胧的状态&#xff0c;说的出来&#xff0c;但又不是完全说的出来&#xff0c;今天我们就以架构设计的角度尝试解开Spring的神秘面纱。 本篇文章以由浅…

RK3566 linux加入uvc app

SDK中external/uvc_app/目录提供了将板卡模拟成uvc camera的功能。 一、buildroot使能uvc_app 1、进入到buildroot目录 在sdk目录下执行以下命令&#xff1a; cd buildroot 2、选择defconfig 执行命令&#xff1a; source build/envsetup.sh 输入数字然后回车选择板卡&…

两数之和(Hash表)[简单]

优质博文&#xff1a;IT-BLOG-CN 一、题目 给定一个整数数组nums和一个整数目标值target&#xff0c;请你在该数组中找出"和"为目标值target的那两个整数&#xff0c;并返回它们的数组下标。 你可以假设每种输入只会对应一个答案。但是&#xff0c;数组中同一个元…