linux c/c++ 代码使用 doxygen 自动生成文档
www.doxygen.org 的使用非常方便,下面分成2步介绍一下
1. 注释风格,需要在c/c++代码中按照下面的风格添加注释,基本上还是很顺手的
C++的注释风格 主要使用下面这种样式:即在注释块开始使用三个反斜杠‘/’
文件注释
/**
*@file 文件名
*@brief 概述
*
*详细概述
*
*@author 作者,包含email等
*@version 版本号(maj.min,主版本.分版本格式)
*@date 日期
*/
命名空间的注释
///@brief 简单概述
///
///详细概述
类定义注释
对需要的类增加注释,需要 说明类的设计方法,类的使用指南,说明类的不变项
///@brief 简要概述
///
///详细说明
///
///使用指南设计函数调用可以@ref 函数名 用于引用其他的说明
///
///其他说明,重写父类函数加以特殊实现
///
///@invariant 类不变项,例如哪些值不会超多少多少
///
class xxx
{…
数据声明注释
行尾说明
Type varName;///< 说明
多行说明
///说明
///
///
Type varName;
函数注释规范
///@brief 简单概述
///
///详细说明
///@param[in|out] 参数名,in,out表示输入还是输出
///@pre 前者条件
///@return 说明
///@retval 返回值 说明, 这个是可选的
///@post 说明函数完成后的世界状态
代码标记数值规范
///@todo 将要做的代码
///@bug 表示此处的bug描述
枚举变量的注释示例
/// 颜色的枚举定义
///
/// 该枚举定义了系统中需要用到的颜色\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 <name> [<header-file>] [<header-name>] eg: @class CTest "inc/class.h" |
@exception |
可能 产生的异常描述 eg: @exception 本函数 执行可能会产生超出范围的异常 |
==================
2 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 目录,然后就可以从浏览器访问文档了,下面是我的项目的文档界面
下面这个是win上面使用的例子:http://wildpointer.net/2012/04/14/doxygen_graphviz/
其他参考:
http://blog.csdn.net/blood008/article/details/6567169
转载于:https://www.cnblogs.com/jiayy/p/doxygen.html
linux c/c++ 代码使用 doxygen 自动生成文档相关推荐
- 用doxygen自动生成文档
1. 添加符合doxygen解析规则的注释 (比如函数说明,函数参数/返回值说明) 用qt-creator可以在函数上方一行键入"/**",然后直接回车,就可以自动生成默认的格式. ...
- MQL5 代码自动生成文档
1. 简介 大多数 Java 代码编写者熟悉可通过 JavaDocs 创建的自动生成文档.其思路是以一种半结构化的方式向代码添加注释,然后可以将这些注释提取到易于导航的帮助文件. C++ 世界也有若干 ...
- php代码自动生成文档-phpDocumentor
概述 PHPDocumentor 能够由你的代码自动生成文档.是一个用PHP写的强盛的文档主动生成对象,可以直接使用命令来处理.对有范例解释的php顺序,可以快速生成具有布局清楚.彼此参照.索引等功效 ...
- django集成Sphinx,为项目自动生成文档
Sphinx是一个工具,可以轻松创建智能和漂亮的文档,他与Python自带的pydoc是同一类产品,但比pydoc更加优秀,还有很多主题可以选择,平时在开发过程中,我们看到的第三方包的文档,基本上都是 ...
- Objective-C自动生成文档工具:appledoc
作者 iOS_小松哥 关注 2016.12.13 15:47* 字数 919 阅读 727评论 10喜欢 35 由于最近琐事比较多,所以好久没有写文章了.今天我们聊一聊Objective-C自动生成文 ...
- Objective-C 自动生成文档工具:appledoc
来源:iOS_小松哥 www.jianshu.com/p/fd4d8d6b6177 如有好文章投稿,请点击 → 这里了解详情 由于最近琐事比较多,所以好久没有写文章了.今天我们聊一聊Objective ...
- docwizard c++程序文档自动生成工具_如何开发一个基于 TypeScript 的工具库并自动生成文档
为什么用 TypeScript? TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. Any ...
- java动态生成sdk_android、java制作sdk以及自动生成文档
最近一直在做android开发,昨天经理让我写个接口SDK做个接口文档,以便后面的开发. 这让我很焦灼,SDK怎么做?要是只有敲代码还好.可是那个接口文档!!!文档这东西最讨厌了,头都大了 后来查了下 ...
- java如何写安卓接口文档_android、java制作sdk以及自动生成文档
最近一直在做android开发,昨天经理让我写个接口SDK做个接口文档,以便后面的开发. 这让我很焦灼,SDK怎么做?要是只有敲代码还好.可是那个接口文档!!!文档这东西最讨厌了,头都大了 后来查了下 ...
最新文章
- python链表添加多个值_Python基础10之数据结构(下)
- ARM指令寻址方式之: 数据处理指令的寻址方式
- 前端那些年--npm
- Detail when click Custom fields tile in s4
- 两千内给力的大屏手机(二)
- android 图片拍照,Android获取图片拍照时间
- 机器学习 Machine Learning中正则化的学习笔记~
- HDU 1024 Max Sum Plus Plus
- 最好用的WIN7 系统下载
- MVC获取客户端IP地址方法
- dcdc转换器计算机显示,DC-DC转换器的问题
- 深圳Python培训:100天从新手到Python大师
- python读取svg转emf_玩玩矢量图标,SVG转换EMF
- 戴尔t40服务器自动开机,新安装的戴尔T40服务器风扇不转了是什么原因?
- 树莓派通过Pin2脚供电的注意事项
- react中引入百度地图时,去掉百度地图的logo和信息
- 双目立体视觉建立深度图_从单幅图像到双目立体视觉的3D目标检测算法
- seaborn调色板 color, hls, cubehelix, dark, diverging_palette
- 一个模拟斗地主的小程序
- uniapp canvas绘制弧形圆环