Merge branch 'master' into feat/fixes_#3409

Author: christophfroehlich

joint_limits/include/joint_limits/data_structures.hpp

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-/// \author Sai Kishor Kothakota
+/// @author Sai Kishor Kothakota
 
 #ifndef JOINT_LIMITS__DATA_STRUCTURES_HPP_
 #define JOINT_LIMITS__DATA_STRUCTURES_HPP_

joint_limits/include/joint_limits/joint_limiter_interface.hpp

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-/// \author Denis Stogl
+/// @author Denis Stogl
 
 #ifndef JOINT_LIMITS__JOINT_LIMITER_INTERFACE_HPP_
 #define JOINT_LIMITS__JOINT_LIMITER_INTERFACE_HPP_
@@ -38,18 +38,19 @@ class JointLimiterInterface
 
   virtual ~JointLimiterInterface() = default;
 
-  /// Initialization of every JointLimiter.
   /**
+   * @brief Initialize every JointLimiter.
+   *
    * Initialization of JointLimiter for defined joints with their names.
    * Robot description topic provides a topic name where URDF of the robot can be found.
    * This is needed to use joint limits from URDF (not implemented yet!).
    * Override this method only if initialization and reading joint limits should be adapted.
    * Otherwise, initialize your custom limiter in `on_init` method.
    *
-   * \param[in] joint_names names of joints where limits should be applied.
-   * \param[in] param_itf node parameters interface object to access parameters.
-   * \param[in] logging_itf node logging interface to log if error happens.
-   * \param[in] robot_description_topic string of a topic where robot description is accessible.
+   * @param[in] joint_names names of joints where limits should be applied.
+   * @param[in] param_itf node parameters interface object to access parameters.
+   * @param[in] logging_itf node logging interface to log if error happens.
+   * @param[in] robot_description_topic string of a topic where robot description is accessible.
    */
   virtual bool init(
     const std::vector<std::string> & joint_names,
@@ -132,7 +133,7 @@ class JointLimiterInterface
   }
 
   /**
-   * Wrapper init method that accepts the joint names and their limits directly
+   * @brief Initialize joints from directly provided names and limits.
    */
   virtual bool init(
     const std::vector<std::string> & joint_names,
@@ -160,7 +161,8 @@ class JointLimiterInterface
   }
 
   /**
-   * Wrapper init method that accepts pointer to the Node.
+   * @brief Initialize joints using a Node pointer.
+   *
    * For details see other init method.
    */
   virtual bool init(
@@ -173,7 +175,8 @@ class JointLimiterInterface
   }
 
   /**
-   * Wrapper init method that accepts pointer to the LifecycleNode.
+   * @brief Initialize joints using a LifecycleNode pointer.
+   *
    * For details see other init method.
    */
   virtual bool init(
@@ -191,14 +194,15 @@ class JointLimiterInterface
     return on_configure(current_joint_states);
   }
 
-  /** \brief Enforce joint limits to desired joint state for multiple physical quantities.
+  /**
+   * @brief Enforce joint limits to desired joint state for multiple physical quantities.
    *
    * Generic enforce method that calls implementation-specific `on_enforce` method.
    *
-   * \param[in] current_joint_states current joint states a robot is in.
-   * \param[in,out] desired_joint_states joint state that should be adjusted to obey the limits.
-   * \param[in] dt time delta to calculate missing integrals and derivation in joint limits.
-   * \returns true if limits are enforced, otherwise false.
+   * @param[in] current_joint_states current joint states a robot is in.
+   * @param[in,out] desired_joint_states joint state that should be adjusted to obey the limits.
+   * @param[in] dt time delta to calculate missing integrals and derivation in joint limits.
+   * @return true if limits are enforced, otherwise false.
    */
   virtual bool enforce(
     const JointLimitsStateDataType & current_joint_states,
@@ -211,46 +215,53 @@ class JointLimiterInterface
   virtual void reset_internals() = 0;
 
 protected:
-  /** \brief Method is realized by an implementation.
+  /**
+   * @brief Initialize the limiter's internal states and libraries.
    *
    * Implementation-specific initialization of limiter's internal states and libraries.
-   * \returns true if initialization was successful, otherwise false.
+   * @return true if initialization was successful, otherwise false.
    */
   virtual bool on_init() = 0;
 
-  /** \brief Method is realized by an implementation.
+  /**
+   * @brief Configure the limiter's internal states and libraries.
    *
    * Implementation-specific configuration of limiter's internal states and libraries.
-   * \returns true if initialization was successful, otherwise false.
+   * @return true if initialization was successful, otherwise false.
    */
   virtual bool on_configure(const JointLimitsStateDataType & current_joint_states) = 0;
 
-  /** \brief Method is realized by an implementation.
+  /**
+   * @brief Enforce joint limits for multiple dependent physical quantities.
    *
    * Filter-specific implementation of the joint limits enforce algorithm for multiple dependent
    * physical quantities.
    *
-   * \param[in] current_joint_states current joint states a robot is in.
-   * \param[in,out] desired_joint_states joint state that should be adjusted to obey the limits.
-   * \param[in] dt time delta to calculate missing integrals and derivation in joint limits.
-   * \returns true if limits are enforced, otherwise false.
+   * @param[in] current_joint_states current joint states a robot is in.
+   * @param[in,out] desired_joint_states joint state that should be adjusted to obey the limits.
+   * @param[in] dt time delta to calculate missing integrals and derivation in joint limits.
+   * @return true if limits are enforced, otherwise false.
    */
   virtual bool on_enforce(
     const JointLimitsStateDataType & current_joint_states,
     JointLimitsStateDataType & desired_joint_states, const rclcpp::Duration & dt) = 0;
 
-  /** \brief Checks if the logging interface is set.
-   * \returns true if the logging interface is available, otherwise false.
+  /**
+   * @brief Checks if the logging interface is set.
+   *
+   * @return true if the logging interface is available, otherwise false.
    *
-   * \note this way of interfacing would be useful for instances where the logging interface is not
+   * @note this way of interfacing would be useful for instances where the logging interface is not
    * available, for example in the ResourceManager or ResourceStorage classes.
    */
   bool has_logging_interface() const { return node_logging_itf_ != nullptr; }
 
-  /** \brief Checks if the parameter interface is set.
-   * \returns true if the parameter interface is available, otherwise false.
+  /**
+   * @brief Checks if the parameter interface is set.
+   *
+   * @return true if the parameter interface is available, otherwise false.
    *
-   * * \note this way of interfacing would be useful for instances where the logging interface is
+   * @note this way of interfacing would be useful for instances where the logging interface is
    * not available, for example in the ResourceManager or ResourceStorage classes.
    */
   bool has_parameter_interface() const { return node_param_itf_ != nullptr; }

joint_limits/include/joint_limits/joint_limits.hpp

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-/// \author Adolfo Rodriguez Tsouroukdissian
+/// @author Adolfo Rodriguez Tsouroukdissian
 
 #ifndef JOINT_LIMITS__JOINT_LIMITS_HPP_
 #define JOINT_LIMITS__JOINT_LIMITS_HPP_
@@ -24,7 +24,8 @@
 namespace joint_limits
 {
 /**
- * JointLimits structure stores values from from yaml definition or `<limits>` tag in URDF.
+ * @brief Store joint limits values from YAML definition or URDF `<limits>` tag.
+ *
  * The mapping from URDF attributes to members is the following:
  *   lower --> min_position
  *   upper --> max_position
@@ -107,8 +108,7 @@ struct JointLimits
 };
 
 /**
- * SoftJointLimits stores values from the `<safety_controller>` tag of URDF.
- * The meaning of the fields are:
+ * @brief Store soft joint limits values from the URDF `<safety_controller>` tag.
  *
  * An element can contain the following attributes:
  *

joint_limits/include/joint_limits/joint_limits_helpers.hpp

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-/// \author Adrià Roig Moreno
+/// @author Adrià Roig Moreno
 
 #ifndef JOINT_LIMITS__JOINT_LIMITS_HELPERS_HPP_
 #define JOINT_LIMITS__JOINT_LIMITS_HELPERS_HPP_
@@ -33,15 +33,15 @@ constexpr double OUT_OF_BOUNDS_EXCEPTION_TOLERANCE = 0.0087;
 }  // namespace internal
 
 /**
- * @brief Updates the previous command with the desired command.
+ * @brief Update the previous command with the desired command.
  * @param prev_command The previous command to update.
  * @param desired The desired command which is limited.
  */
 void update_prev_command(
   const JointControlInterfacesData & desired, JointControlInterfacesData & prev_command);
 
 /**
- * @brief Checks if a value is limited by the given limits.
+ * @brief Check if a value is limited by the given limits.
  * @param value The value to check.
  * @param min The minimum limit.
  * @param max The maximum limit.
@@ -50,7 +50,7 @@ void update_prev_command(
 bool is_limited(double value, double min, double max);
 
 /**
- * @brief Computes the position limits based on the velocity and acceleration limits.
+ * @brief Compute the position limits based on the velocity and acceleration limits.
  * @param joint_name The name of the joint.
  * @param limits The joint limits.
  * @param act_vel The actual velocity of the joint.
@@ -66,7 +66,7 @@ PositionLimits compute_position_limits(
   const std::optional<double> & prev_command_pos, double dt);
 
 /**
- * @brief Computes the velocity limits based on the position and acceleration limits.
+ * @brief Compute the velocity limits based on the position and acceleration limits.
  * @param joint_name The name of the joint.
  * @param limits The joint limits.
  * @param act_pos The actual position of the joint.
@@ -80,7 +80,7 @@ VelocityLimits compute_velocity_limits(
   const std::optional<double> & prev_command_vel, double dt);
 
 /**
- * @brief Computes the effort limits based on the position and velocity limits.
+ * @brief Compute the effort limits based on the position and velocity limits.
  * @param limits The joint limits.
  * @param act_pos The actual position of the joint.
  * @param act_vel The actual velocity of the joint.
@@ -92,7 +92,7 @@ EffortLimits compute_effort_limits(
   const std::optional<double> & act_vel, double /*dt*/);
 
 /**
- * @brief Computes the acceleration limits based on the change in velocity and acceleration and
+ * @brief Compute the acceleration limits based on the change in velocity and acceleration and
  * deceleration limits.
  * @param limits The joint limits.
  * @param desired_acceleration The desired acceleration.