首飞的博客
0%

利用Doxygen生成代码文档

发表于 更新于 分类于

Doxygen是一个代码文档生成工具。它从代码文件中提取注释并可生成多种文档形式。如：网页文档HTML，RTF (MS-Word)，PDF等等。同时也可生成函数之间的调用和文件的依赖关系图表。

Doxygen除了支持C++语言外还支持C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors)，甚至它也支持硬件描述语言VHDL。

doxygen的安装

  1. 使用apt安装doxygen
1
sudo apt install doxygen
  1. 使用最新版的二进制安装（该种方式想对于第一种，可安装最新的版本）

doxygen的下载页面：

https://www.doxygen.nl/download.html

找到下面图片所示，下载二进制包。

image-20220816083732322

可以看到，该二进制包是在Ubuntu 20.04环境下编译的，可能不适用于其他版本的系统。

解压二进制包后，进入包文件夹，使用下面的命令安装。

1
sudo make install

makefile中没有安装doxywizard。

我们可以手动拷贝到/usr/local/bin/中。

1
2
cd doxygen-1.9.4/bin
sudo cp doxywizard /usr/local/bin/

Doxywizard是一个GUI应用。可以用它来生成Doxygen的配置文件。

  1. 安装graphviz

Graphviz是开源的图形可视化软件。它可以将结构化的信息以图表的形式显示出来。doxygen可以调用Graphviz显示函数的调用关系。

1
sudo apt install graphviz
  1. htmlhelp说明

htmlhelp是一个可以将html网页文件生成一个独立的chm文件的软件工具。但它目前只能运行在windows环境下。

如果需要生成chm文件，可将doxygen生成的网页文件拷贝至windows环境下，然后用htmlhelp来生成chm文件。

注释和文档效果

  1. 头文件中添加如下函数注释。
1
2
3
4
5
6
/**
 * @brief Deactivates action server
 * @param state Reference to LifeCycle node state
 * @return SUCCESS or FAILURE
 */
nav2_util::CallbackReturn on_deactivate(const rclcpp_lifecycle::State & state) override;

上面的注释方式是采用Javadoc风格的。其实还有其他的风格。可以查看下面的网址了解：

https://www.doxygen.nl/manual/docblocks.html#cppblock

文档中对应的显示效果如下。

另外一个示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
/**
* @brief Construct the TebConfig using default values.
* @warning If the \b rosparam server or/and \b dynamic_reconfigure (rqt_reconfigure) node are used,
*	     the default variables will be overwritten: \n
*	     E.g. if \e base_local_planner is utilized as plugin for the navigation stack, the initialize() method will register a
* 	     dynamic_reconfigure server. A subset (not all but most) of the parameters are considered for dynamic modifications.
* 	     All parameters considered by the dynamic_reconfigure server (and their \b default values) are
* 	     set in \e PROJECT_SRC/cfg/TebLocalPlannerReconfigure.cfg. \n
* 	     In addition the rosparam server can be queried to get parameters e.g. defiend in a launch file.
* 	     The plugin source (or a possible binary source) can call loadRosParamFromNodeHandle() to update the parameters.
* 	     In \e summary, default parameters are loaded in the following order (the right one overrides the left ones): \n
* 		<b>TebConfig Constructor defaults << dynamic_reconfigure defaults << rosparam server defaults</b>
*/
TebConfig()
{

}

\b 可以加粗后面的关键词，\e表示后面的词进行斜体显示，<b> ...</b> 可将其中的内容加粗显示。\n 则是显式添加回车。

文档上的显示效果：

再一个示例：

1
2
3
4
5
6
7
/**
 * A pure virtual member.
 * @see testMe()
 * @param c1 the first argument.
 * @param c2 the second argument.
 */
 virtual void testMeToo(char c1,char c2) = 0;

显示效果：

注意，注释中添加的关键字。

@brief 表示后面的内容是对函数功能的描述

@warning 一些警告信息

@param 传入参数的说明

@return 函数返回结果的说明

@see 方便跳转相关联的函数

另外注意，函数的注释放在头文件和源文件中效果是等同的。

  1. 项目中的markdown文档会生成相应的页面

  1. 对类成员的注释
1
2
3
std::string odom_topic; //!< Topic name of the odometry message, provided by the robot driver or simulator
std::string map_frame; //!< Global planning frame
std::string node_name; //!< node name used for parameter event callback

文档显示效果：

  1. 注释一个结构体
1
2
3
4
5
6
7
 //! Trajectory related parameters
 struct Trajectory
 {
   double teb_autosize; //!< Enable automatic resizing of the trajectory w.r.t to the temporal resolution (recommended)
...
   int control_look_ahead_poses; //! Index of the pose used to extract the velocity command
 } trajectory; //!< Trajectory related parameters

结构体上面的 //! Trajectory related parameters是对结构体的描述。

下面的//!< Trajectory related parameters是对声明的类成员的描述。注意与上面符号的区别，这里多了一个<。其实<说明了注释的方向。

  1. 注释一个类
1
2
3
4
5
6
7
8
/**
 * @class TebConfig
 * @brief Config class for the teb_local_planner and its components.
 */
class TebConfig
{
    ...
}

生成文档

生成配置文件

用下面的命令生成配置模板文件

1
doxygen -g

运行完后默认会生成一个名为Doxyfile的配置文件。

然后就可以根据需求手动修改配置文件了。

当然我们也可以基于图形界面来修改该文件。

运行doxywizard

1
doxywizard

然后点击file->open打开Doxyfile配置文件。

或者直接使用

1
doxywizard Doxyfile

常用的参数配置

  1. 打开调用关系图

显示效果如下：

上图显示了该函数调用了哪些函数，然后又被什么函数调用了。

  1. 当JAVADOC_AUTOBRIEF参数设置为YES时，会将下面的注释内容直接当成简介描述。
1
2
3
/**
 *  A test class. A more elaborate class description.
 */

如果设置成NO的话，则需要添加@brief显式标记。

1
2
3
/**
 *  @brief A test class. A more elaborate class description.
 */
  1. 如果希望生成的文档中包含源码，则需要如下配置

生成文档

在具有Doxyfile配置文件的目录下运行doxygen即可生成文档。

1
doxygen

也可以在doxywizard里点击运行doxygen来生成文档。

觉得有用就点赞吧！

我是首飞，一个帮大家填坑的机器人开发攻城狮。

另外在公众号《首飞》内回复“机器人”获取精心推荐的C/C++，Python，Docker，Qt，ROS1/2等机器人行业常用技术资料。

公众号