您现在的位置是:首页 > 正文

【Doxygen】Doxygen使用教程(个人总结)

2024-01-30 22:46:35阅读 0

【Doxygen】Doxygen使用教程(个人总结)

简介Doxygen

引言.什么是Doxygen?

Doxygen 是一个程序的文件产生工具,可将程序中的特定批注转换成为说明文件。通常我们在写程序时,或多或少都会写上批注,但是对于其它人而言,要直接探索程序里的批注,与打捞铁达尼号同样的辛苦。大部分有用的批注都是属于针对函式,类别等等的说明。所以,如果能依据程序本身的结构,将批注经过处理重新整理成为一个纯粹的参考手册,对于后面利用您的程序代码的人而言将会减少许多的负担。不过,反过来说,整理文件的工作对于您来说,就是沉重的负担。
Doxygen 就是在您写批注时,稍微按照一些它所制订的规则。接着,他就可以帮您产生出漂亮的文档了。

因此,Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写,第二便是利用Doxygen的工具来产生文档。

目前Doxygen可处理的程序语言包含:

  • C/C++

  • Java

  • IDL (Corba, Microsoft及KDE-DCOP类型)

而可产生出来的文档格式有:

  • HTML

  • XML

  • LaTeX

  • RTF

  • Unix Man Page

而其中还可衍生出不少其它格式。HTML可以打包成CHM格式,而LaTeX可以透过一些工具产生出PS或是PDF文档。

要想使用Doxygen,需要三大步骤

一.安装Doxygen

1.Doxygen及其相关内容下载

1.1Doxygen下载

由于国内墙了Doxygen的官网,但sourceforge还是可以使用

http://sourceforge.NET/projects/doxygen/?source=dlp 进行下载

本文使用的为Doxygen 1.8.3.1

安装,我们将在配置的时候使用doxywizard,Doxygen的GUI版本。

1.2HTML Help Workshop下载

Doxygen 使用这个工具可以生成 CHM 格式的文档。

如果你希望你的Doxygen自动生成chm,那么请下载HTML Help Workshop,我们将要使用当中的hcc.exe文件以及相关dll

https://docs.microsoft.com/zh-cn/previous-versions/windows/desktop/htmlhelp/microsoft-html-help-downloads?redirectedfrom=MSDN 进行下载

下载其中的htmlhelp.exe并安装,记住安装目录,我们将在Doxygen配置时使用。

1.3 Graphviz

Graphviz在Doxygen用于自动生成类图的工具。graphviz 是一个由AT&T实验室启动的开源工具包,用于绘制DOT语言脚本描述的图形。Doxygen 使用 graphviz 自动生成类之间和文件之间的调用关系图,如不需要此功能可不安装该工具包。

登陆官网发现被墙了,只能在天朝大局域网内随便找个方便的连接了。

https://www.graphviz.org/,

安装并记录安装目录,同样我们一会需要配置Doxygen

二.Doxygen的配置

Doxygen 产生文档可以分为三个步骤。一是在程序代码中加上符合Doxygen所定义批注格式二是使用Doxywizard进行配置三是使用Doxygen来产生批注文档

2.1基本配置

在基本配置中,会介绍一些关于Doxygen的基本配置,例如各种乱码,输出内容等。

首先我们打开开始-》所有程序-》Doxygen-》doxywizard

在开始之前,打开Doxygen GUI frontend的File,保存到你需要做测试的目录

会出现一个Doxyfile的配置文件,修改选项后保存,下次通过Doxygen打开这个文件可以还原该项目的配置

2.2 进行配置

Doxygen 1.7.4 主界面如下图 1 所示。

在这里插入图片描述
说明:

1,Doxygen 工作目录,就是用来存放配置文件的目录。
2,递归搜索源文件目录需要选上。

选择 wizard 标签下的 Output Topics
相关配置说明如下图 2 所示。
在这里插入图片描述

选择 wizard 标签下的 Diagrams Topics
相关配置说明如下图 3 所示。

在这里插入图片描述

说明:如果选择这个选项之前需要先安装了 Graphviz 工具包。

选择 expert 标签下的 Project Topics
相关配置说明如下图 4 所示。

在这里插入图片描述

说明:编码格式,UTF-8 是首选。如果需要显示中文则选择GB2312.

TAB_SIZE 主要是帮助文件中代码的缩进尺寸,譬如@code和@endcode段中代码的排版,建议设置成4。

OPTIMIZE_OUTPUT_FOR_C 这个选项选择后,生成文档的一些描述性名称会发生变化,主要是符合C习惯。如果

是纯C代码,建议选择。

SUBGROUPING这个选项选择后,输出将会按类型分组

选择 expert 标签下的 Build

在这里插入图片描述

Build页面,这个页面是生成帮助信息中比较关键的配置页面:

EXTRACT_ALL 表示:输出所有的函数,但是privatestatic函数不属于其管制。

EXTRACT_PRIVATE 表示:输出private函数。

EXTRACT_STATIC 表示:输出static函数。同时还有几个EXTRACT,相应查看文档即可。

HIDE_UNDOC_MEMBERS 表示:那些没有使用doxygen格式描述的文档(函数或类等)就不显示了。当然,如果EXTRACT_ALL被启用,那么这个标志其实是被忽略的。

INTERNAL_DOCS 主要指:是否输出注解中的@internal部分。如果没有被启动,那么注解中所有的@internal部分都

将在目标帮助中不可见。

CASE_SENSE_NAMES 表示:是否关注大小写名称,注意,如果开启了,那么所有的名称都将被小写。对于C/C++这种

字母相关的语言来说,建议永远不要开启。

HIDE_SCOPE_NAMES 表示:域隐藏,建议永远不要开启。

SHOW_INCLUDE_FILES 表示:是否显示包含文件,如果开启,帮助中会专门生成一个页面,里面包含所有包含文件的列

表。

INLINE_INFO :如果开启,那么在帮助文档中,inline函数前面会有一个inline修饰词来标明。

SORT_MEMBER_DOCS :如果开启,那么在帮助文档列表显示的时候,函数名称会排序,否则按照解释的顺序显

示。

GENERATE_TODOLIST :是否生成TODOLIST页面,如果开启,那么包含在@todo注解中的内容将会单独生成并显

示在一个页面中,其他的GENERATE选项同。

SHOW_USED_FILES :是否在函数或类等的帮助中,最下面显示函数或类的来源文件。

SHOW_FILES :是否显示文件列表页面,如果开启,那么帮助中会存在一个一个文件列表索引页面。

选择 expert 标签下的 Input Topics
相关配置说明如下图 5 所示。
在这里插入图片描述

说明:输入的源文件的编码,要与源文件的编码格式相同。如果源文件不是UTF-8编码最好转一下。

总结:

我查看到我的代码文件是GB2312的(查看方法(以VS2008为例):文件->高级保存选项)。此时如果这里还是选择UTF-8,那么会导致编译出来的CHM文件中的中文会有乱码。

在这里插入图片描述

选择 expert 标签下的 HTML Topics
相关配置说明如下图 6 所示。

在这里插入图片描述

说明:

1,CHM_FILE文件名需要加上后缀(`xx.chm`)。

2,如果在 Wizard 的 Output Topics 中选择了 prepare for compressed HTML (.chm)选项,此处就会要求选择 hhc.exe 程序的位置。在 windows help workshop 安装目录下可以找到 hhc.exe。

3,为了解决DoxyGen生成的CHM文件的左边树目录的中文变成了乱码,CHM_INDEX_ENCODING中输入GB2312即可。

4,GENERATE_CHI 表示索引文件是否单独输出,建议关闭。否则每次生成两个文件,比较麻烦。

5,TOC_EXPAND 表示是否在索引中列举成员名称以及分组(譬如函数,枚举)名称。

之后在Expert的Dot中勾选CLASS_DIAGRAMS,UML_LOOK
在这里插入图片描述

为了减少chm体积,在DOT_IMAGE_FORMAT中选择gif或者jpg,均可。

最后在DOT_PATH下面填入dot.exe的路径

在这里插入图片描述

配置GraphViz 暂缺

选择 Run 标签
相关配置说明如下图 7 所示。

在这里插入图片描述

点击 Run doxygen 按钮, Doxygen 就会从源代码中抓取符合规范的注释生成你定制的格式的文档。

四.撰写正确格式的批注

并非所有程序代码中的批注都会被Doxygen 所处理。您必需依照正确的格式撰写。原则上,Doxygen 仅处理与程序结构相关的批注,如Function,Class ,档案的批注等。对于Function内部的批注则不做处理。Doxygen可处理下面几种类型的批注。

JavaDoc类型:

/**
 * ... 批注 ...
 */


Qt类型:

/*!
 * ... 批注 ...
 */

     
单行型式的批注:

/// ... 批注 ...

或    

//! ... 批注 ...

要使用哪种型态完全看自己的喜好。以笔者自己来说,大范围的注解我会使用JavaDoc 型的。单行的批注则使用"///" 的类型。

此外,由于Doxygen 对于批注是视为在解释后面的程序代码。也就是说,任何一个批注都是在说明其后的程序代码。如果要批注前面的程式码则需用下面格式的批注符号。

/*!< ... 批注 ... */
/**< ... 批注 ... */
//!< ... 批注 ...
///< ... 批注 ...

上面这个方式并不适用于任何地方,只能用在class 的member或是
function的参数上。

举例来说,若我们有下面这样的class。

class MyClass {undefined
    public:
        int member1 ;
        int member2:
        void member_function();
};

加上批注后,就变成这样:

  /**
     * 我的自订类别说明 ...
     */
    class MyClass {undefined
        public:
            int member1 ; ///< 第一个member说明 ...
            int member2:  ///< 第二个member说明 ...
            int member_function(int a, int b);
    };
    
    /**
     * 自订类别的member_funtion说明 ...
     *
     * @param a 参数a的说明
     * @param b 参数b的说明
     *
     * @return 传回a+b。
     */ 
    int MyClass::member_function( int a, int b ) 
    {undefined
        return a+b ;
    }

当您使用Doxygen 产生说明文档时,Doxygen 会帮您parsing 您的程式码。并且依据程序结构建立对应的文件。然后再将您的批注,依据其位置套入于正确的地方。您可能已经注意到,除了一般文字说明外,还有一些其它特别的指令,像是@param@return 等。这正是Doxygen 另外一个重要的部分,因为一个类别或是函式其实都有固定几个要说明的部分。为了让Doxygen 能够判断,所有我们就必需使用这些指令,来告诉Doxygen 后面的批注是在说明什么东西。Doxygen 在处理时,就会帮您把这些部分做特别的处理或是排版。甚至是制作
参考连结。

首先,我们先说明在Doxygen 中对于类别或是函数批注的一个特定格
式。

   /**
    * class或function的简易说明...
    *
    * class或function的详细说明...
    * ...
    */

上面这个例子要说的是,在Doxygen 处理一个class 或是function注解时,会先判断第一行为简易说明。这个简易说明将一直到空一行的出现。或是遇到第一个"." 为止。之后的批注将会被视为详细说明。

两者的差异在于Doxygen 在某些地方只会显示简易说明,而不显示详细说明。如:class 或function的列表。

另一种比较清楚的方式是指定@brief的指令。这将会明确的告诉
Doxygen,何者是简易说明。例如:

/**
    * @brief class或function的简易说明...
    *
    * class或function的详细说明...
    * ...
    */

除了这个class 及function外,Doxygen 也可针对档案做说明,条件
是该批注需置于档案的前面。主要也是利用一些指令,通常这部分注
解都会放在档案的开始地方。如:

  /*! \file myfile.h
       \brief 档案简易说明
   
       详细说明.
       
       \author 作者信息
   */

如您所见,档案批注约略格式如上,请别被"" 所搞混。其实,“”
与"@" 都是一样的,都是告诉Doxygen 后面是一个指令。两种在
Doxygen 都可使用。笔者自己比较偏好使用"@"。

接着我们来针对一些常用的指令做说明:

@file 档案的批注说明。
@author 作者的信息
作者的信息 用于class 或function的批注中,后面为class 或function的简易说明。
@param 格式为@param arg_name 参数说明主要用于函式说明中,后面接参数的名字,然后再接关于该参数的说明。
@return 后面接函数传回值的说明。用于function的批注中。说明该函数的传回值。
@retval 格式为@retval value 传回值说明主要用于函式说明中,说明特定传回值的意义。所以后面要先接一个传回值。然后在放该传回值的说明。

Doxygen 所支持的指令很多,有些甚至是关于输出排版的控制。您可从Doxygen的使用说明中找到详尽的说明。

下面我们准备一组example.h 及example.cpp 来说明Doxygen 批注的使用方式:

example.h:

/**
    * @file 本范例的include档案。
    *
    * 这个档案只定义example这个class。
    *
    * @author garylee@localhost
    */
           
   #define EXAMPLE_OK  0   ///< 定义EXAMPLE_OK的宏为0。
   
   /**
    * @brief Example class的简易说明
    *
    * 本范例说明Example class。
    * 这是一个极为简单的范例。
    * 
    */
   class Example {undefined
       private:
           int var1 ; ///< 这是一个private的变数
       public:
           int var2 ; ///< 这是一个public的变数成员。
           int var3 ; ///< 这是另一个public的变数成员。
           void ExFunc1(void); 
           int ExFunc2(int a, char b);
           char *ExFunc3(char *c) ;
   };

example.cpp:

 /**
    * @file 本范例的程序代码档案。
    *
    * 这个档案用来定义example这个class的
    * member function。
    *
    * @author garylee@localhost
    */
   
   /**
    * @brief ExFunc1的简易说明
    *
    * ExFunc1没有任何参数及传回值。
    */
   void Example::ExFunc1(void)
   {undefined
       // empty funcion.
   }

   /**
    * @brief ExFunc2的简易说明
    *
    * ExFunc3()传回两个参数相加的值。
    *
    * @param a 用来相加的参数。
    * @param b 用来相加的参数。
    * @return 传回两个参数相加的结果。
    */
   int ExFunc2(int a, char b)
   {undefined
       return (a+b);
   }
   
   /**
    * @brief ExFunc3的简易说明
    *
    * ExFunc3()只传回参数输入的指标。
    *
    * @param c 传进的字符指针。
    * @retval NULL 空字符串。
    * @retval !NULL 非空字符串。
    */
   char * ExFunc2(char * c)
   {undefined
       return c;
   }    

完整实例:

/**
* Created by Qxt on 2016/10/13
* @brief 测试Doxygen的使用
*/
public class TestClass {undefined


 /// 枚举
 enum TYPE
   {undefined
       TYPE_01,/*!< 枚举项01 */
       TYPE_02,///< 枚举项02
   };


 int member1;///<第一个member说明


   /**
    *
    * @see 参考项 http://www.cnblogs.com/tianzhijiexian/
    * @brief 求和
    * @author QXT
    * @date 2016/10/13 13:37:56
    * @version 0.1
    * @retval c 描述返回值的类型
    * @note 注解,可以是详细的注解
    * @remarks   备注事项(remaks)
    * @attention 注意事项(attention)
    * @warning 警告信息
    * @param a 用来相加的参数
    * @param b 用来相加的参数
    * @return 传回两个参数相加的结果
    *
    */
   int AddFun(int a,int b){undefined
       return (a+b);
   }
}

网站文章

  • Qt - Clion使用cmake运行QtCreator创建的qmake项目,无改动切换自如

    Qt - Clion使用cmake运行QtCreator创建的qmake项目,无改动切换自如

    Clion使用cmake运行QtCreator创建的qmake项目,这也正是我希望的。既可用qt的qmake在QtCreator运行、debug、发布等,同时也可以享受clion编码的便捷(对于jetbrains idea用户来说)。

    2024-01-30 22:46:28
  • 线程数据共享和安全 -ThreadLocal

    线程数据共享和安全 -ThreadLocal

    线程数据共享和安全 -ThreadLocal 1.什么是 ThreadLocal ThreadLocal 的作用,可以实现在同一个线程数据共享, 从而解决多线程数据安全问题. ThreadLocal ...

    2024-01-30 22:45:58
  • 【Android】App开发-动画效果篇

    【Android】App开发-动画效果篇

    在我们玩手机的过程中,如果我们点击某一个页面时,会出现一个页面动画加载或者动画效果的现象。现在我们就来看看App开发中是如何实现动画效果的。

    2024-01-30 22:45:53
  • map函数

    map函数 map() 会根据提供的函数对指定序列做映射。 第一个参数 function 以参数序列中的每一个元素调用 function 函数,返回包含每次 function 函数返回值的新列表。我们...

    2024-01-30 22:45:45
  • RabbitMQ消息队列常见面试题总结

    RabbitMQ消息队列常见面试题总结

    RabbitMQ消息队列常见面试题总结;1、什么是消息队列?消息队列的优缺点?2、Kafka、ActiveMQ、RabbitMQ、RocketMQ的区别?3、如何保证消息不被重复消费?4、如何保证消息不丢失,进行可靠性传输?5、如何保证消息的有序性?6、如何处理消息堆积情况?7、如何保证消息队列的高可用?

    2024-01-30 22:45:38
  • 一百二十、Kettle——从Hive全量导入到ClickHouse

    一百二十、Kettle——从Hive全量导入到ClickHouse

    用kettle把Hive数据同步到ClickHouse

    2024-01-30 22:45:09
  • 22.0 Pycharm中编写js代码

    22.0 Pycharm中编写js代码

    【代码】22.0 Pycharm中编写js代码。

    2024-01-30 22:45:03
  • 使用openpyxl玩转excel数据

    访问单元格的基本操作

    2024-01-30 22:44:55
  • Vue组件化之VueComponent介绍

    Vue组件化之VueComponent介绍

    简介这篇文章主要介绍的是VueComponent函数。<!DOCTYPE html><html lang="en"><head> <meta charset="UTF-8"> <meta ...

    2024-01-30 22:44:26
  • chatgpt赋能python:Python实现隐藏Excel列的方法

    chatgpt赋能python:Python实现隐藏Excel列的方法

    本文由chatgpt生成,文章没有在chatgpt生成的基础上进行任何的修改。以上只是chatgpt能力的冰山一角。作为通用的Aigc大模型,只是展现它原本的实力。对于颠覆工作方式的ChatGPT,应...

    2024-01-30 22:44:22