ros2/common_interfaces

Improve Documentation of JointState and MultiDOFJointState for clarity and differentiation

tfoote opened this issue · 1 comments

This is a follwup to the pre Foxy Message API review

There were multiple comments about differentiation and clarity. Along the lines of the MultiDOFJointState represents the same information as the JointState for Multi Degreee of Freedom Joints as such the naming is specifically following the same pattern for a similar class of joints.

JointState.msg and MultiDOFJointState.msg have really similar names, and it’s commented in MultiDOF that they follow the same structure.
However, the structure is not similar in terms of the internal types used.

The internal types are direct analogs to the JointState message.

  • name -> joint_names: This was made more explicit as the original was considered ambiguous, but changing the existing implementation would be disruptive.
  • position -> transform: A transform is the multiDOF equivalent of a position.
  • velocity -> twist: The multi dimensional version of velocity.
  • effort -> wrench: The multi dimensional representation of torques.

MultiDOFJointState is actually plural states

State is already ambiguous as to how many items it's reflecting and the message can reflect 0 or more elements. Any change in this area would still be slightly ambiguous so we should default to keeping it stable at it is to avoid disruption.