Improve description of state elements

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

sdf/1.12/joint_state.sdf

@@ -1,6 +1,9 @@
 <!-- State information for a joint -->
 <element name="joint_state" required="*">
-  <description>Joint angle</description>
+  <description>
+    The joint state element encapsulates variables within a joint that may
+    change over time, currently limited to the joint angle.
+  </description>
 
   <attribute name="name" type="string" default="__default__" required="1">
     <description>Name of the joint</description>

sdf/1.12/light_state.sdf

@@ -1,6 +1,9 @@
 <!-- State information for a light -->
 <element name="light_state" required="*">
-  <description>Light state</description>
+  <description>
+    The light state element encapsulates variables within a light that may
+    change over time, currently limited to its pose.
+  </description>
 
   <attribute name="name" type="string" default="__default__" required="1">
     <description>Name of the light</description>

sdf/1.12/link_state.sdf

@@ -1,6 +1,10 @@
 <!-- State information for a link -->
 <element name="link_state" required="*">
-  <description>Link state</description>
+  <description>
+    The link state element encapsulates variables within a link that may
+    change over time, including pose, velocity, acceleration, applied wrench,
+    and the state of attached collisions.
+  </description>
 
   <attribute name="name" type="string" default="__default__" required="1">
     <description>Name of the link</description>

sdf/1.12/model_state.sdf

@@ -1,6 +1,10 @@
 <!-- State information for a model -->
 <element name="model_state" required="*">
-  <description>Model state</description>
+  <description>
+    The model state element encapsulates variables within a model that may
+    change over time, including object poses, the states of its nested models
+    and links and joints, and changes in model scale.
+  </description>
 
   <attribute name="name" type="string" default="__default__" required="1">
     <description>Name of the model</description>

sdf/1.12/state.sdf

@@ -1,5 +1,12 @@
 <!-- State Info -->
 <element name="state" required="*">
+  <description>
+    The state element encapsulates variables within a world that may change
+    over time, including object poses, dynamic states such as velocity and
+    acceleration, a description of objects added to the world, and a list
+    of objects deleted from the world.
+  </description>
+
   <!-- Name of the world this state applies to -->
   <attribute name="world_name" type="string" default="__default__" required="1">
     <description>Name of the world this state applies to</description>
@@ -22,14 +29,14 @@
   </element>
 
   <element name="insertions" required="0">
-    <description>A list containing the entire description of entities inserted.</description>
+    <description>A list containing the entire description of entities inserted into the world.</description>
     <include filename="model.sdf" required="+"/>
     <include filename="light.sdf" required="+"/>
     <include filename="joint.sdf" required="+"/>
   </element>
 
   <element name="deletions" required="0">
-    <description>A list of names of deleted entities/</description>
+    <description>A list of names of entities deleted from the world./</description>
     <element name="name" type="string" default="__default__" required="+">
       <description>The name of a deleted entity.</description>
     </element>