doxygen简单介绍

1. 概述

   doxygen官方文档

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

2. 安装

   sudo apt-get install doxygen doxygen-gui

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

3. 使用

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

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

   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目录,里面有生成的文档.

4. 使用doxygen时的注释应该如何写

   注解官方文档 doxygen Sepcial Command

   注解

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

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

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

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

5. 注释中常用的标记

   注意 一般来说,详细的描述都是在\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 文件的创建日期

6. 结构体或者类成员变量的说明

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

7. 有关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生成了.