doxygen简单介绍

doxygen简单介绍

概述
doxygen官方文档

这是一个生成文档的工具,可以通过代码文件中的注释进行文档的生成,通过画图工具可以绘制调用过程和文件包含关系等

安装
sudo apt-get install doxygen doxygen-gui

doxygen-gui是一个可以通过图形界面生成配置文件的工具

使用
只要在代码注释中做了特殊的标记,就使用这个工具进行文档的生成

过程如下(详细配置以后再说)

mkdir doc;cd doc

doxygen -g ;#生成一个配置文件名字为Doxyfile

打开Doxyfile,修改里面的配置(粗体是使用的配置)
GENERATE_LATEX = YES| NO #这个是配置是不是生成latex(pdf)

DISABLE_INDEX = YES | NO #索引是不是有,可能影响搜索功能

GENERATE_TREEVIEW = YES | NO #是不是生成右侧的树型索引

EXTRACT_ALL = YES | NO #这个配置生成文档的大小,我们向让它详细,就配置YES

INPUT = ../ #这个配置输入的文件目录,源文件在那个目录下.

执行 doxygen Doxygen 就能生成一个html目录,里面有生成的文档.

使用doxygen时的注释应该如何写
注解官方文档
doxygen Sepcial Command

注解
一般来说,注释都是说明的后面代码的,如果想让注释说明前面的代码,可以使用在注明写入doxygen文档的标记后紧跟一个<来说明,比如做结构体或者成员变量的注释的时候,注意,写在后面的注解只能指明注解说明的是前 一 行的内容

在注释后在写一个前一个字符就是告诉doxygen这个注释就是要写入文档的, 比如

C // 是普通注释,///就是写入doxygen文档的注释了, /* */ 是普通注释, /** */ 就是写入doxygen文档的注释了,

PYTHON 中 # 是普通注释, ## 就是写入doxygen文档的注释了.

注释中常用的标记
注意 一般来说,详细的描述都是在\brief后面空一行开始的,如果不空一行,都会即使换行了也会认为是brief的内容的多余的空行doxygen都会认为是空一行的,
空一行的解释 空一行不只是一个 \n ,是在一行内,只有doxygen识别出写入文档的标记 之前的内容,如下所示:

/**         (这里是标记开始写入doxygen库)
* \brief   (这里标记这是一个简要说明)
*          (这里是空行的样式)
*          (这里如果有信息,就认为是详细注释的内容)
*          (多余的空行doxygen会认为只有一个空行)
*/

使用 \xxxx 或者 @xxx 标识一个标记,标记会让doxygen特殊处理后面的注释.

常用

\brief 简短说明,这个会在概述部分出现的说明,旁边会有一个more按钮,点击查看详情,

\param 参数说明,做在函数前面是说明每个参数的作用,doxygen会做特殊处理,换个颜色

\return 说明一个函数的返回值

\retval 说明返回值类型

说明类标记

\note 这个是说明部分,doxygen会起一个 Note 或者 说明 段落进行说明 这个标签之后的注释内容

\attention 注意

\warning 警告信息

\exception 可能产生的异常描述

会产生连接的标记

\see 后面加一个class名称或者function名称,doxygen会生成一个指向这个函数详细说明的连接

\enum [MY_ENUM|CTest::Enum] 后面加一个枚举,

\var [Variable] 引用某个变量

\class 引用某个类

下面是给文件注释的时候常用的标记,一般用在文件的开头

\file 文件名(这个一般写文件的文件名称,在文件里看到本文件的文件名称,不要写别的,注释规范,具体为啥我也不知道啊)

\brief 这个和对函数和类的注释的含义是一样的,对一个文件的简单注释

\author 说明这个文件的作者

\version [1.1] 版权声明

\date 文件的创建日期

结构体或者类成员变量的说明
没有这类特殊标记的,doxygen会分析代码的结构,我们只要在对应的变量前面或者 统一行的后面(使用<) 做写入doxygen文档的标记就行了.

有关doxygen生成图表的配置.
准备工作:

sudo apt-get install graphvize doxygen doxygen-gui

配置步骤:

运行 doxywizard
文件打开一个使用doxygen -g 生成的配置文件

在 Wizard => Mode 下配置 All Entities 和 Include cross-referenced source code in the output ,在下面选择一个针对语言的优化选项
在 Wizard => Output 下配置输出格式,
生成图表这一步是关键 在 Wizard => Diagrams 下配置生成的图表类型勾选 Call graphs 和 Called by graphs 等等,就会生成对应图表
在 Export => Project 下选择输出语言 这个语言是值doxygen的网也框架的语言,选英文也是可以输出中文注释的,
生成图表这一步是关键 在 Export => Dot 下勾选 CALL_GRAPH CALLER_GRAPH 等,配置DOT_PATH (一般配置为/usr/bin)
在 Run 下点击 Run doxygen 开始生成文档,关闭的时候会提示是否保存,点击保存,以后就可以使用doxygen生成了.