如何贡献 Doxygen 评论

本指南将介绍并概述贡献 Doxygen 注释的良好做法。

学习目标

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

说明

在为 MoveIt（或任何代码）做出贡献时，请确保您的代码始终可读且注释良好。使用 Doxygen 注释可以实现文档标准化，并确保所有贡献都包含某些信息。 Doxygen 的主要优点之一是它允许以一致、可读的格式自动生成 API 文档。

插件可以自动为以下程序创建 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 API 的操作指南：doc:此处。

请参阅 Doxygen 文档指南`此处 <https://www.doxygen.nl/manual/docblocks.html>`_。