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

2024-01-17 09:44

本文主要是介绍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 目录,然后就可以从浏览器访问文档了,下面是我的项目的文档界面

这篇关于C++ 程序文档生成器(doxygen)使用说明的文章就介绍到这儿,希望我们推荐的文章对编程师们有所帮助!



http://www.chinasem.cn/article/615623

相关文章

Zookeeper安装和配置说明

一、Zookeeper的搭建方式 Zookeeper安装方式有三种,单机模式和集群模式以及伪集群模式。 ■ 单机模式:Zookeeper只运行在一台服务器上,适合测试环境; ■ 伪集群模式:就是在一台物理机上运行多个Zookeeper 实例; ■ 集群模式:Zookeeper运行于一个集群上,适合生产环境,这个计算机集群被称为一个“集合体”(ensemble) Zookeeper通过复制来实现

中文分词jieba库的使用与实景应用(一)

知识星球:https://articles.zsxq.com/id_fxvgc803qmr2.html 目录 一.定义: 精确模式(默认模式): 全模式: 搜索引擎模式: paddle 模式(基于深度学习的分词模式): 二 自定义词典 三.文本解析   调整词出现的频率 四. 关键词提取 A. 基于TF-IDF算法的关键词提取 B. 基于TextRank算法的关键词提取

使用SecondaryNameNode恢复NameNode的数据

1)需求: NameNode进程挂了并且存储的数据也丢失了,如何恢复NameNode 此种方式恢复的数据可能存在小部分数据的丢失。 2)故障模拟 (1)kill -9 NameNode进程 [lytfly@hadoop102 current]$ kill -9 19886 (2)删除NameNode存储的数据(/opt/module/hadoop-3.1.4/data/tmp/dfs/na

Hadoop数据压缩使用介绍

一、压缩原则 (1)运算密集型的Job,少用压缩 (2)IO密集型的Job,多用压缩 二、压缩算法比较 三、压缩位置选择 四、压缩参数配置 1)为了支持多种压缩/解压缩算法,Hadoop引入了编码/解码器 2)要在Hadoop中启用压缩,可以配置如下参数

Makefile简明使用教程

文章目录 规则makefile文件的基本语法:加在命令前的特殊符号:.PHONY伪目标: Makefilev1 直观写法v2 加上中间过程v3 伪目标v4 变量 make 选项-f-n-C Make 是一种流行的构建工具,常用于将源代码转换成可执行文件或者其他形式的输出文件(如库文件、文档等)。Make 可以自动化地执行编译、链接等一系列操作。 规则 makefile文件

【C++ Primer Plus习题】13.4

大家好,这里是国中之林! ❥前些天发现了一个巨牛的人工智能学习网站,通俗易懂,风趣幽默,忍不住分享一下给大家。点击跳转到网站。有兴趣的可以点点进去看看← 问题: 解答: main.cpp #include <iostream>#include "port.h"int main() {Port p1;Port p2("Abc", "Bcc", 30);std::cout <<

使用opencv优化图片(画面变清晰)

文章目录 需求影响照片清晰度的因素 实现降噪测试代码 锐化空间锐化Unsharp Masking频率域锐化对比测试 对比度增强常用算法对比测试 需求 对图像进行优化,使其看起来更清晰,同时保持尺寸不变,通常涉及到图像处理技术如锐化、降噪、对比度增强等 影响照片清晰度的因素 影响照片清晰度的因素有很多,主要可以从以下几个方面来分析 1. 拍摄设备 相机传感器:相机传

C++包装器

包装器 在 C++ 中,“包装器”通常指的是一种设计模式或编程技巧,用于封装其他代码或对象,使其更易于使用、管理或扩展。包装器的概念在编程中非常普遍,可以用于函数、类、库等多个方面。下面是几个常见的 “包装器” 类型: 1. 函数包装器 函数包装器用于封装一个或多个函数,使其接口更统一或更便于调用。例如,std::function 是一个通用的函数包装器,它可以存储任意可调用对象(函数、函数

C++11第三弹:lambda表达式 | 新的类功能 | 模板的可变参数

🌈个人主页: 南桥几晴秋 🌈C++专栏: 南桥谈C++ 🌈C语言专栏: C语言学习系列 🌈Linux学习专栏: 南桥谈Linux 🌈数据结构学习专栏: 数据结构杂谈 🌈数据库学习专栏: 南桥谈MySQL 🌈Qt学习专栏: 南桥谈Qt 🌈菜鸡代码练习: 练习随想记录 🌈git学习: 南桥谈Git 🌈🌈🌈🌈🌈🌈🌈🌈🌈🌈🌈🌈🌈�

JAVA智听未来一站式有声阅读平台听书系统小程序源码

智听未来,一站式有声阅读平台听书系统 🌟&nbsp;开篇:遇见未来,从“智听”开始 在这个快节奏的时代,你是否渴望在忙碌的间隙,找到一片属于自己的宁静角落?是否梦想着能随时随地,沉浸在知识的海洋,或是故事的奇幻世界里?今天,就让我带你一起探索“智听未来”——这一站式有声阅读平台听书系统,它正悄悄改变着我们的阅读方式,让未来触手可及! 📚&nbsp;第一站:海量资源,应有尽有 走进“智听