doxygen简单介绍,一篇入门

最新推荐文章于 2023-07-14 10:04:06 发布

weixin_34372728

最新推荐文章于 2023-07-14 10:04:06 发布

阅读量196

点赞数

文章标签： python

原文链接：https://my.oschina.net/u/2265334/blog/1609960

版权

2019独角兽企业重金招聘Python工程师标准>>>

doxygen简单介绍

概述

doxygen官方文档

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

sudo apt-get install doxygen doxygen-gui

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

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

过程如下(详细配置以后再说)
1. mkdir doc;cd doc
2. doxygen -g ;#生成一个配置文件名字为Doxyfile
3. 打开Doxyfile,修改里面的配置(粗体是使用的配置)
  
  GENERATE_LATEX = YES| NO #这个是配置是不是生成latex(pdf)
  
  DISABLE_INDEX = YES | NO #索引是不是有,可能影响搜索功能
  
  GENERATE_TREEVIEW = YES | NO #是不是生成右侧的树型索引
  
  EXTRACT_ALL = YES | NO #这个配置生成文档的大小,我们向让它详细,就配置YES
  
  INPUT = ../ #这个配置输入的文件目录,源文件在那个目录下.
4. 执行 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

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