Doxygen
是一个代码文档生成工具。它从代码文件中提取注释并可生成多种文档形式。如:网页文档HTML,RTF (MS-Word),PDF等等。同时也可生成函数之间的调用和文件的依赖关系图表。
Doxygen
除了支持C++
语言外还支持C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors),甚至它也支持硬件描述语言VHDL。
apt
安装doxygen
sudo apt install doxygen
doxygen
的下载页面:
https://www.doxygen.nl/download.html
找到下面图片所示,下载二进制包。
可以看到,该二进制包是在Ubuntu 20.04
环境下编译的,可能不适用于其他版本的系统。
解压二进制包后,进入包文件夹,使用下面的命令安装。
sudo make install
makefile
中没有安装doxywizard
。
我们可以手动拷贝到/usr/local/bin/
中。
cd doxygen-1.9.4/bin
sudo cp doxywizard /usr/local/bin/
Doxywizard
是一个GUI
应用。可以用它来生成Doxygen
的配置文件。
graphviz
Graphviz
是开源的图形可视化软件。它可以将结构化的信息以图表的形式显示出来。doxygen
可以调用Graphviz
显示函数的调用关系。
sudo apt install graphviz
htmlhelp
说明htmlhelp
是一个可以将html
网页文件生成一个独立的chm
文件的软件工具。但它目前只能运行在windows
环境下。
如果需要生成chm
文件,可将doxygen
生成的网页文件拷贝至windows
环境下,然后用htmlhelp
来生成chm
文件。
/**
* @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
文档中对应的显示效果如下。
另外一个示例:
/**
* @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
则是显式添加回车。
文档上的显示效果:
再一个示例:
/**
* 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
方便跳转相关联的函数
另外注意,函数的注释放在头文件和源文件中效果是等同的。
markdown
文档会生成相应的页面 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
文档显示效果:
//! 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
是对声明的类成员的描述。注意与上面符号的区别,这里多了一个<
。其实<
说明了注释的方向。
/**
* @class TebConfig
* @brief Config class for the teb_local_planner and its components.
*/
class TebConfig
{
...
}
用下面的命令生成配置模板文件
doxygen -g
运行完后默认会生成一个名为Doxyfile
的配置文件。
然后就可以根据需求手动修改配置文件了。
当然我们也可以基于图形界面来修改该文件。
运行doxywizard
doxywizard
然后点击file
->open
打开Doxyfile
配置文件。
或者直接使用
doxywizard Doxyfile
显示效果如下:
上图显示了该函数调用了哪些函数,然后又被什么函数调用了。
JAVADOC_AUTOBRIEF
参数设置为YES
时,会将下面的注释内容直接当成简介描述。/**
* A test class. A more elaborate class description.
*/
如果设置成NO
的话,则需要添加@brief
显式标记。
/**
* @brief A test class. A more elaborate class description.
*/
在具有Doxyfile
配置文件的目录下运行doxygen
即可生成文档。
doxygen
也可以在doxywizard
里点击运行doxygen
来生成文档。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。