如何贡献 Doxygen 注释

本指南将介绍贡献 Doxygen 注释的良好实践。在向 MoveIt（或任何代码库）贡献时，请确保你的代码清晰易读、注释完善。使用 Doxygen 注释可以实现文档标准化，并确保所有贡献都包含某些必要信息。Doxygen 的主要优势之一是能够以一致、可读的格式自动生成 API 文档。

学习目标

如何编写有用的 Doxygen 注释
一些实用的 Doxygen 插件

说明

以下插件可用于自动化生成 Doxygen 文档：

以及适用于许多其他 IDE 的插件。

一般来说，Doxygen 注释至少应包含对所注释内容的简短描述。如果函数有输入参数和输出参数，对它们的描述也很有帮助。

下面提供几个示例：

/** @brief Check for robot self collision. Any collision between any pair of links is checked for, NO collisions are
*   ignored.
*
*  @param req A CollisionRequest object that encapsulates the collision request
*  @param res A CollisionResult object that encapsulates the collision result
*  @param state The kinematic state for which checks are being made */
virtual void checkSelfCollision(const CollisionRequest& req, CollisionResult& res,
                                const moveit::core::RobotState& state) const = 0;

/** @brief A bounding volume hierarchy (BVH) implementation of a tesseract contact manager */
class BulletBVHManager
{
...

    /** @brief Instantiate and return a instance of a subclass of Type using our
*         pluginlib::ClassLoader.
* @param class_id A string identifying the class uniquely among
*        classes of its parent class.  rviz::GridDisplay might be
*        rviz/Grid, for example.
* @param error_return If non-NULL and there is an error, *error_return is set to a description of the problem.
* @return A new instance of the class identified by class_id, or NULL if there was an error.
*
* If makeRaw() returns NULL and error_return is not NULL, *error_return will be set.
* On success, *error_return will not be changed. */
    virtual Type* makeRaw(const QString& class_id, QString* error_return = nullptr) {

这些示例提供了输入和输出的类型与描述，并简要说明了函数或类的作用。

进一步阅读

欢迎浏览仓库，查看更多 Doxygen 注释示例。查看与你将要贡献的代码类似的代码及其注释，是学习 Doxygen 最简单的方式。

参见关于如何在本地生成 Doxygen API 的操作指南：这里。

参见 Doxygen 文档指南：这里。