Add more documentation to messages

Author: urfeex

control_msgs/action/ExecuteMotionPrimitiveSequence.action

@@ -1,3 +1,5 @@
+# A list of MotionPrimitive messages that are executed in sequence. They don't have to be of the
+# same type, as long as the robot supports executing them one after another.
 MotionPrimitiveSequence trajectory
 ---
 int32 SUCCESSFUL = 0
@@ -7,4 +9,5 @@ int32 OLD_HEADER_TIMESTAMP = -3
 int32 error_code
 string error_string
 ---
-uint8 current_primitive_index # How far are we in the actual trajectory?
+# Index of the currently executed motion primitive in the sequence.
+uint8 current_primitive_index

control_msgs/msg/MotionArgument.msg

@@ -1,2 +1,4 @@
+# Key Value pair to be used in MotionPrimitive messages
+
 string argument_name
 float64 argument_value

control_msgs/msg/MotionPrimitive.msg

@@ -8,10 +8,16 @@ int8 type -1 # one of the above
 
 float64 blend_radius
 
+# MotionArguments are meant to be used as vendor-specific or use-case-specific arguments to
+# MotionPrimitive messages. This is to avoid bloating the MotionPrimitive message with all possible
+# uses cases but rather add specific data using as a list of key-value pairs, which is what this
+# message represents.
 MotionArgument[] additional_arguments # (max) velocity, (max) acceleration, efficiency
 
 # Targets should be either specified through joint configurations or Cartesian poses.
 # Depending on the motion type and implementation, there might be multiple poses allowed.
 # For example, circular motions are often specified as via and target
+# Usually one of these is empty, in some edge cases even both can be empty, when all input is given
+# in the more flexible MotionArgument[] field.
 geometry_msgs/PoseStamped[] poses
 float64[] joint_positions