Doxygen简介
在编写大量代码时,或者与多人协作进行开发时,文字记录很重要(文档说明书或注释),很多人在代码编写的时候,一边写具体代码,一边写专门的说明书,这样效率就不是很高了。这里就推荐使用Doxygen,Doxygen它是一种编写软件参考文档的工具,可以将我们代码中按规范写的注释经过处理,转化为说明书。它也可以提取代码的结构生成包含依赖图(include dependency graphs),继承图(inheritance diagram)以及协作图(collaboration diagram)来可视化文档,源代码等之间的关系。
使用Doxygen的好处:
- Doxygen 使用注释生成说明书,它让我们养成写注释的好习惯,方便我们记忆。如果一段复杂的代码没有添加注释的话,很有可能在过去一段时间后,我们需要花费大量的时间回忆这段代码干了些什么。
- Doxygen有自己的注释规范,所以不用格外花心思去构思如何去写注释,用哪一种风格去写,在团队中能形成统一,从而专注于构思代码。
- 在团队协作中,通过Doxygen生成的说明书或者在源代码里的注释,让协作者更好的理解自己写的代码。
总而言之,使用Doxygen最大的帮助就是节省时间,并提高生产力。Doxygen官方网站是:https://www.doxygen.nl/index.html,有关Doxygen的介绍没有比它更加权威的了。
Doxygen安装入门
Ubuntu 18.04 下载安装Doxygen和Doxygen图形界面:
sudo apt install –y doxygen doxygen-gui
Windows下载安装,登入网站:https://doxygen.nl/download.html,下载如doxygen-1.9.7-setup.exe,根据提示安装。
因为博主用的发开工具是VScode,VScode里也有Doxygen的插件,在Extension里搜索Doxygen Documentation Generator并安装。
Doxygen所支持的语言:
Programm language:C, C++, Lex, C#, Objective-C, IDL, Java, PHP, Python, Fortran等。
Hardware description language:VHDL,默认不支持Verilog,需要doxverilog插件。
Doxygen注释语法
1. 块注释
Javadoc style:
/**
* ... text ...
*/
Qt style:
/*!
* ... text ...
*/
两种风格中间的 * 都是可选的,比如:
/** /*!
... text ... ... text ...
* / */
第三种风格由两个comment(//) 加上格外的 / 或者 !组成:
/// //!
/// ... text ... //! ... text ...
/// //!
第四种风格为了让块注释更加显眼:
/// /***************************
/// ... text ... * ... text ...
/// ****************************/
2. 行间注释
行间注释一般可写为:
/** ... text ... */ /// ... text ...
3. 变量后注释
为了跟行间注释区分,在变量后注释需要格外添加 < 符号,如在 int var 后面添加注释,这几种风格都是可以的:
int var; /*!< ... text ... */
int var; /**< ... text ... */
int var; //!< ... text ...
int var; ///< ... text ...
4. 头文件注释
头文件注释的方法非常多样,下面仅为一个例子:
/***********************************************
* Copyright 2021 - 2021, All right reserved
************************************************/
/**
*@file doxygen.h
*@brief This is the doxygen header file
*@author Christian
*@date 2023/7/15
*@see https://www.doxygen.nl/index.html
*/
例如@brief是Doxygen的结构化命令,结构化命令通常以 @ 或 \ 开头,如下面两种风格都是可以的:
/** @brief */
/** \brief */
一般结构化命令后面跟的内容为:
@file 文件名
@brief 一段简要的说明
@author 文件作者
@date 修改日期
@see 额外参考类型,比如有用过的链接
通过添加结构化命令可以最后在说明书里生成相应的内容,比如添加上述的结构化命令,可以在说明书里看到类似的:
![](https://i-blog.csdnimg.cn/blog_migrate/8624aa4f8cb695db5f882f71fcb0fc9e.png)
另外头文件也可以添加其他内容,以VOLK(Vector Optimized Library of Kernels)库中volk_8ic_deinterleave_real_8i.h为例子,它在头文件里添加了这样的 Doxygen注释:
/*!
* \page volk_8ic_deinterleave_real_8i
*
* \b Overview
*
* Deinterleaves the complex 8-bit char vector into just the I (real)
* vector.
*
* <b>Dispatcher Prototype</b>
* \code
* void volk_8ic_deinterleave_real_8i(int8_t* iBuffer, const lv_8sc_t* complexVector,
* unsigned int num_points) \endcode
*
* \b Inputs
* \li complexVector: The complex input vector.
* \li num_points: The number of complex data values to be deinterleaved.
*
* \b Outputs
* \li iBuffer: The I buffer output data.
*
* \b Example
* \code
* int N = 10000;
*
* volk_8ic_deinterleave_real_8i();
*
* volk_free(x);
* \endcode
*/
最后在生成的说明书里会转化成下面的内容,这种注释比较适合写一些算法的注释。
![](https://i-blog.csdnimg.cn/blog_migrate/fa884d1f5a0ca713122f8d01f908e741.png)
5. API group 注释
如果代码比较复杂,分成了很多模块,为了表达模块之间的包含关系,可以使用group注释,一般也是写在头文件里,基本语法如下, \defgroup 表示生成一个模块,\ingroup 表示当前生成模块的所属模块:
/**
*\brief Math Library
*\defgroup math
*\ingroup base
*/
最后在生成的说明书里会转化成下面的内容, 另外group注释也可以生成一些协作图等。
6. 变量注释
变量的注释有很多种,下面以一个结构体注释为例子, 在结构体定义前面添加brief结构化命令,在结构体的成员变量后添加变量后注释:
/**
*\brief this is a box struct
*/
typedef struct {
int length; /**< length of the box */
int width; /**< width of the box */
int height; /**< height of the box */
} box_t;
最后在生成的说明书里会转化成下面的内容:
![](https://i-blog.csdnimg.cn/blog_migrate/2ba1ecb3f526103fa5bbb71f709bd8d5.png)
7. API 函数注释
函数的注释博主认为是注释里最重要的,因为协作者最想了解的就是函数的调用方法,函数注释的结构化命令有很多,我们可以选择使用:
@brief 函数简单介绍
@param 变量的介绍,可以用[in][out]表示输入输出方向
@return 返回值描述
@retval 具体返回值及含义
@see 链接信息
@note 备注信息
@warning 函数使用者需要注意的信息
@author 函数作者
@date 修改时间
下面为一个doxygen_func函数注释的例子:
/**
* @brief this is a doxygen function
* @param[out] c - output value c
* @param[in] a - input value a
* @param[in] b - input value b
* @return 0 of success, otherwise failure
*/
int doxygen_func(int* c, int a, int b);
最后在生成的说明书里我们可以看到下面类似的内容:
![](https://i-blog.csdnimg.cn/blog_migrate/7d83de3a28844018ce1e4ca80ad3b0cb.png)
在下篇的博客,博主会带来Doxygen说明书的生成方法。