Merge pull request #12 in OSHC/syropod_highlevel_controller from feature/pose_comments to master

* commit '229ac39e2e96ea2152df3bf5b110e5b996ffb499':
  Fixed typos in pose header
  Updated comments in pose header

Author: Jayasinghe, Oshada (Data61, Pullenvale)

include/syropod_highlevel_controller/pose.h

@@ -11,40 +11,33 @@
 
 #include "standard_includes.h"
 
-/*******************************************************************************************************************//**
- * Class defining a 3d position and rotation using Eigen Vector3 and Quaternion classes
-***********************************************************************************************************************/
-class Pose
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+/// Class defining a 3d position and rotation using Eigen Vector3 and Quaternion classes.
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 {
 public:
-  
-  /**
-   * Blank contructor
-   */
+  /// Blank contructor
   inline Pose(void) {};
 
-  /**
-   * Pose class constructor
-   */
+  /// Pose class constructor.
+  /// @param[in] position The vector input to be set as the position vector of the pose
+  /// @param[in] rotation The vector input to be set as the rotation vector of the pose
   inline Pose(const Vector3d& position, const Quaterniond& rotation)
   {
     position_ = position;
     rotation_ = rotation;
   };
 
-  /**
-   * Pose class constructor for geometry_msgs/Pose
-   */
+  /// Pose class constructor for geometry_msgs/Pose.
+  /// @param[in] pose The geometry_msgs/Pose input to be set as the pose
   inline Pose(const geometry_msgs::Pose& pose)
   {
     position_ = Vector3d(pose.position.x, pose.position.y, pose.position.z);
     rotation_ = Quaterniond(pose.orientation.w, pose.orientation.x, pose.orientation.y, pose.orientation.z);
   };
 
-  /**
-   * Checks for NaN values within pose elements
-   * @return Bool denoting whether pose contains no NaN values
-   */
+  /// Checks for NaN values within pose elements.
+  /// @return Bool denoting whether pose contains no NaN values
   inline bool isValid(void)
   {
     return abs(position_[0]) < UNASSIGNED_VALUE &&
@@ -56,19 +49,16 @@ class Pose
            abs(rotation_.z()) < UNASSIGNED_VALUE;
   }
 
-  /**
-   * Pose class constructor for geometry_msgs/Transform
-   */
+  /// Pose class constructor for geometry_msgs/Transform.
+  /// @param[in] transform The geometry_msgs/Transform input to be used to construct the pose
   inline Pose(const geometry_msgs::Transform& transform)
   {
     position_ = Vector3d(transform.translation.x, transform.translation.y, transform.translation.z);
     rotation_ = Quaterniond(transform.rotation.w, transform.rotation.x, transform.rotation.y, transform.rotation.z);
   };
 
-  /**
-   * Returns a conversion of this pose object into a geometry_msgs::Pose
-   * @return The converted geometry_msgs::Pose message
-   */
+  /// Returns a conversion of this pose object into a geometry_msgs::Pose.
+  /// @return The converted geometry_msgs::Pose message
   inline geometry_msgs::Pose toPoseMessage(void)
   {
     geometry_msgs::Pose pose;
@@ -82,10 +72,8 @@ class Pose
     return pose;
   }
 
-  /**
-   * Returns a conversion of this pose object into a geometry_msgs::Transform
-   * @return The converted geometry_msgs::Transform message
-   */
+  /// Returns a conversion of this pose object into a geometry_msgs::Transform.
+  /// @return The converted geometry_msgs::Transform message
   inline geometry_msgs::Transform toTransformMessage(void)
   {
     geometry_msgs::Transform transform;
@@ -99,40 +87,32 @@ class Pose
     return transform;
   }
 
-  /**
-   * Operator to check if two poses are equivalent
-   * @params[in] pose The pose that is checked for equivalency against *this
-   * @return Bool defining if input and *this pose are equivalent.
-   */
+  /// Operator to check if two poses are equivalent.
+  /// @param[in] pose The pose that is checked for equivalency against *this
+  /// @return Bool defining if input and *this pose are equivalent
   inline bool operator==(const Pose& pose)
   { 
     return position_.isApprox(pose.position_) && rotation_.isApprox(pose.rotation_);
   }
 
-  /**
-   * Operator to check if two poses are NOT equivalent
-   * @params[in] pose The pose that is checked for non-equivalency against *this
-   * @return Bool defining if input and *this pose are non-equivalent.
-   */
+  /// Operator to check if two poses are NOT equivalent.
+  /// @param[in] pose The pose that is checked for non-equivalency against *this
+  /// @return Bool defining if input and *this pose are non-equivalent
   inline bool operator!=(const Pose& pose)
   {
     return !position_.isApprox(pose.position_) || !rotation_.isApprox(pose.rotation_);
   }
 
-  /**
-   * Returns inverse of pose
-   * @return The inverse of *this pose
-   */
+  /// Returns inverse of pose.
+  /// @return The inverse of *this pose
   inline Pose operator~(void) const 
   { 
     return Pose((rotation_.conjugate())._transformVector(-position_), rotation_.conjugate());
   }
 
-  /**
-   * Transforms this pose according to an input geometry_msgs::Transform
-   * @params[in] transform The input transformation msg
-   * @return The transformed pose
-   */
+  /// Transforms this pose according to an input geometry_msgs::Transform.
+  /// @param[in] transform The input transformation msg
+  /// @return The transformed pose
   inline Pose transform(const geometry_msgs::Transform& transform) const
   {
     Vector3d position(position_ + Vector3d(transform.translation.x,
@@ -145,11 +125,9 @@ class Pose
     return Pose(position, rotation);
   }
 
-  /**
-   * Transforms this pose according to an input transformation matrix constructed from DH matrices
-   * @params[in] transform The input transformation matrix
-   * @return The transformed pose
-   */
+  /// Transforms this pose according to an input transformation matrix constructed from DH matrices.
+  /// @param[in] transform The input transformation matrix
+  /// @return The transformed pose
   inline Pose transform(const Matrix4d& transform) const
   {
     Pose return_pose;
@@ -163,31 +141,25 @@ class Pose
     return return_pose;
   }
 
-  /**
-   * Transforms an input vector into the reference frame of this pose.
-   * @params[in] vec The input vector to be transformed into this pose's reference frame.
-   * @return The transformed vector.
-   */
+  /// Transforms an input vector into the reference frame of this pose.
+  /// @param[in] vec The input vector to be transformed into this pose's reference frame
+  /// @return The transformed vector
   inline Vector3d transformVector(const Vector3d& vec) const 
   { 
     return position_ + rotation_._transformVector(vec);
   };
 
-  /**
-   * Transforms an input vector from the reference frame of this pose.
-   * @params[in] vec The input vector to be transformed from this pose's reference frame.
-   * @return The inversly transformed vector
-   */
+  /// Transforms an input vector from the reference frame of this pose.
+  /// @param[in] vec The input vector to be transformed from this pose's reference frame
+  /// @return The inversly transformed vector
   inline Vector3d inverseTransformVector(const Vector3d& vec) const 
   { 
     return (~*this).transformVector(vec);
   };
 
-  /**
-   * Adds input pose to *this pose
-   * @params[in] pose The pose to add from *this pose
-   * @return The combination of *this pose and input pose
-   */
+  /// Adds input pose to *this pose.
+  /// @param[in] pose The pose to add from *this pose
+  /// @return The combination of *this pose and input pose
   inline Pose addPose(const Pose& pose) 
   {
     Pose return_pose = (*this);
@@ -196,11 +168,9 @@ class Pose
     return return_pose;
   }
 
-  /**
-   * Removes input pose from *this pose
-   * @params[in] pose The pose to remove from *this pose
-   * @return The resultant pose after removing input pose from *this pose
-   */
+  /// Removes input pose from *this pose.
+  /// @param[in] pose The pose to remove from *this pose
+  /// @return The resultant pose after removing input pose from *this pose
   inline Pose removePose (const Pose& pose)
   { 
     Pose return_pose = (*this);
@@ -209,32 +179,26 @@ class Pose
     return return_pose;
   };
 
-  /**
-   * Generates interpolation from this pose to target pose using control input between zero and one.
-   * @params[in] control_input A value between 0.0 and 1.0 which defines the progress of interpolation.
-   * @params[in] target_pose The target pose to which interpolation will return with control input of one.
-   * @return The resultant interpolated pose.
-   */
+  /// Generates interpolation from this pose to target pose using control input between zero and one.
+  /// @param[in] control_input A value between 0.0 and 1.0 which defines the progress of interpolation
+  /// @param[in] target_pose The target pose to which interpolation will return with control input of one
+  /// @return The resultant interpolated pose
   inline Pose interpolate (const double& control_input, const Pose& target_pose)
   { 
     Vector3d position = control_input * target_pose.position_ + (1.0 - control_input) * (*this).position_;
     Quaterniond rotation = (*this).rotation_.slerp(control_input, target_pose.rotation_);
     return Pose(position, rotation);
   };
 
-  /**
-   * Returns pose with position and rotation elements set to identity values.
-   * @return The Identity Pose
-   */
+  /// Returns pose with position and rotation elements set to identity values.
+  /// @return The Identity Pose
   inline static Pose Identity(void) 
   { 
     return Pose(Vector3d::Zero(), Quaterniond::Identity()); 
   }
 
-  /**
-   * Returns pose with position and rotation elements all set to undefined values.
-   * @return The Undefined Pose
-   */
+  /// Returns pose with position and rotation elements all set to undefined values.
+  /// @return The Undefined Pose
   inline static Pose Undefined(void) 
   { 
     return Pose(UNDEFINED_POSITION, UNDEFINED_ROTATION);
@@ -247,6 +211,6 @@ class Pose
   EIGEN_MAKE_ALIGNED_OPERATOR_NEW
 };
 
-/***********************************************************************************************************************
-***********************************************************************************************************************/
-#endif /* SYROPOD_HIGHLEVEL_CONTROLLER_POSE_H */
+////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+#endif // SYROPOD_HIGHLEVEL_CONTROLLER_POSE_H