From cd32f6e8a178860649c62327be661b86b199f117 Mon Sep 17 00:00:00 2001
From: Steve Peters <scpeters@openrobotics.org>
Date: Tue, 13 Aug 2024 18:10:38 -0700
Subject: [PATCH] Improve description of state elements

Signed-off-by: Steve Peters <scpeters@openrobotics.org>
---
 sdf/1.12/joint_state.sdf |  5 ++++-
 sdf/1.12/light_state.sdf |  5 ++++-
 sdf/1.12/link_state.sdf  |  6 +++++-
 sdf/1.12/model_state.sdf |  6 +++++-
 sdf/1.12/state.sdf       | 11 +++++++++--
 5 files changed, 27 insertions(+), 6 deletions(-)

diff --git a/sdf/1.12/joint_state.sdf b/sdf/1.12/joint_state.sdf
index 60273b27f..2b64d832c 100644
--- a/sdf/1.12/joint_state.sdf
+++ b/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>
diff --git a/sdf/1.12/light_state.sdf b/sdf/1.12/light_state.sdf
index b0e02da86..54bebb02f 100644
--- a/sdf/1.12/light_state.sdf
+++ b/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>
diff --git a/sdf/1.12/link_state.sdf b/sdf/1.12/link_state.sdf
index a04c8f66f..e59d9e0f1 100644
--- a/sdf/1.12/link_state.sdf
+++ b/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>
diff --git a/sdf/1.12/model_state.sdf b/sdf/1.12/model_state.sdf
index e9905621b..cbbbfd0de 100644
--- a/sdf/1.12/model_state.sdf
+++ b/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>
diff --git a/sdf/1.12/state.sdf b/sdf/1.12/state.sdf
index a7d2d471f..30fbd4e42 100644
--- a/sdf/1.12/state.sdf
+++ b/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>