SetModelState.hh: document xml syntax

Signed-off-by: Steve Peters <[email protected]>

src/systems/set_model_state/SetModelState.hh

@@ -31,16 +31,39 @@ namespace systems
   // Forward declaration
   class SetModelStatePrivate;
 
-  /// \brief This system sets a specified model state during Configure and
-  /// Reset.
-  ///
+  /// \brief This system should be attached to a model and sets a specified
+  /// model state during Configure and Reset using the syntax shown below.
+  /// Currently joint positions and velocities can be set for named joints.
+  /// By default, the units for position are radians for rotational joints
+  /// and meters for translational joints. Likewise the units for velocity
+  /// are radians / second for rotational joints and meters / second
+  /// for translational joints. If the `degrees` attribute is set to "true"
+  /// for a given scalar value, the value will be scaled by (π / 180)
+  /// before being interpreted using default units.
+  /// TODO(scpeters): warn if degrees==true for a translational joint.
+  /** \code{.xml}
+    <model_state>
+      <joint_state name="joint_0">
+        <axis_state>
+          <position degrees="true">60</position>
+          <velocity degrees="true">-30</velocity>
+        </axis_state>
+      </joint_state>
+      <joint_state name="joint_1">
+        <axis_state>
+          <position degrees="true">1.0471975512</position>
+          <velocity degrees="true">-0.5235987756</velocity>
+        </axis_state>
+      </joint_state>
+    </model_state>
+  \endcode */
   /// ## Components
   ///
   /// This system uses the following components:
   ///
   /// - gz::sim::components::JointPositionReset
   /// - gz::sim::components::JointVelocityReset
-  /// TODO: add components to reset link pose and velocity
+  /// TODO(scpeters): add components to reset link pose and velocity
   class SetModelState
       : public System,
         public ISystemConfigure,