[①Doxygen]: 入门，注释语法简介

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     额外参考类型，比如有用过的链接

通过添加结构化命令可以最后在说明书里生成相应的内容，比如添加上述的结构化命令，可以在说明书里看到类似的：

另外头文件也可以添加其他内容，以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
 */

最后在生成的说明书里会转化成下面的内容，这种注释比较适合写一些算法的注释。

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;

最后在生成的说明书里会转化成下面的内容：

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);

最后在生成的说明书里我们可以看到下面类似的内容：

在下篇的博客，博主会带来Doxygen说明书的生成方法。