doxygen简单介绍,一篇入门

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