[atk] Improve documentation related to AtkState and AtkStateSet

[Joanmarie Diggs <joanied src gnome org>]

commit be5805852c8888585575da00c98807196b396610
Author: Joanmarie Diggs <jdiggs igalia com>
Date:   Thu Nov 13 09:11:04 2014 -0500

    Improve documentation related to AtkState and AtkStateSet
    
    https://bugzilla.gnome.org/show_bug.cgi?id=740066

 atk/atkobject.c       |    5 ++++-
 atk/atkstate.c        |    8 ++++----
 atk/atkstateset.c     |   28 ++++++++++++++++++++++------
 docs/atk-sections.txt |    1 -
 4 files changed, 30 insertions(+), 12 deletions(-)
---
diff --git a/atk/atkobject.c b/atk/atkobject.c
index f381df1..3358ea5 100755
--- a/atk/atkobject.c
+++ b/atk/atkobject.c
@@ -1200,7 +1200,10 @@ atk_object_remove_property_change_handler  (AtkObject *accessible,
  * @state: an #AtkState whose state is changed
  * @value: a gboolean which indicates whether the state is being set on or off
  * 
- * Emits a state-change signal for the specified state. 
+ * Emits a state-change signal for the specified state.
+ *
+ * Note that as a general rule when the state of an existing object changes,
+ * emitting a notification is expected.
  **/
 void
 atk_object_notify_state_change (AtkObject *accessible,
diff --git a/atk/atkstate.c b/atk/atkstate.c
index 2334fe8..b715c96 100755
--- a/atk/atkstate.c
+++ b/atk/atkstate.c
@@ -25,12 +25,12 @@
 
 /**
  * SECTION:atkstate
- * @Short_description: An AtkState describes a component's particular state.
+ * @Short_description: An AtkState describes a single state of an object.
  * @Title:AtkState
  *
- * An AtkState describes a component's particular state. The actual
- * state of an component is described by its AtkStateSet, which is a
- * set of AtkStates.
+ * An AtkState describes a single state of an object. The full set of states
+ * that apply to an object at a given time are contained in its #AtkStateSet.
+ * See also #atk_object_ref_state_set and #atk_object_notify_state_change.
  */
 
 static guint last_type = ATK_STATE_LAST_DEFINED;
diff --git a/atk/atkstateset.c b/atk/atkstateset.c
index 1740d05..d240ee6 100755
--- a/atk/atkstateset.c
+++ b/atk/atkstateset.c
@@ -26,11 +26,12 @@
 
 /**
  * SECTION:atkstateset
- * @Short_description: An AtkStateSet determines a component's state set.
+ * @Short_description: An AtkStateSet contains the states of an object.
  * @Title:AtkStateSet
  *
- * An AtkStateSet determines a component's state set. It is composed
- * of a set of AtkStates.
+ * An AtkStateSet is a read-only representation of the full set of #AtkStates
+ * that apply to an object at a given time. This set is not meant to be
+ * modified, but rather created when #atk_object_ref_state_set() is called.
  */
 
 #define ATK_STATE(state_enum)             ((AtkState)((guint64)1 << ((state_enum)%64)))
@@ -115,8 +116,13 @@ atk_state_set_is_empty (AtkStateSet   *set)
  * @set: an #AtkStateSet
  * @type: an #AtkStateType
  *
- * Add a new state for the specified type to the current state set if
- * it is not already present.
+ * Adds the state of the specified type to the state set if it is not already
+ * present.
+ *
+ * Note that because an #AtkStateSet is a read-only object, this method should
+ * be used to add a state to a newly-created set which will then be returned by
+ * #atk_object_ref_state_set. It should not be used to modify the existing state
+ * of an object. See also #atk_object_notify_state_change.
  *
  * Returns: %TRUE if  the state for @type is not already in @set.
  **/
@@ -143,7 +149,12 @@ atk_state_set_add_state (AtkStateSet   *set,
  * @types: (array length=n_types): an array of #AtkStateType
  * @n_types: The number of elements in the array
  *
- * Add the states for the specified types to the current state set.
+ * Adds the states of the specified types to the state set.
+ *
+ * Note that because an #AtkStateSet is a read-only object, this method should
+ * be used to add states to a newly-created set which will then be returned by
+ * #atk_object_ref_state_set. It should not be used to modify the existing state
+ * of an object. See also #atk_object_notify_state_change.
  **/
 void
 atk_state_set_add_states (AtkStateSet   *set,
@@ -240,6 +251,11 @@ atk_state_set_contains_states (AtkStateSet   *set,
  *
  * Removes the state for the specified type from the state set.
  *
+ * Note that because an #AtkStateSet is a read-only object, this method should
+ * be used to remove a state to a newly-created set which will then be returned
+ * by #atk_object_ref_state_set. It should not be used to modify the existing
+ * state of an object. See also #atk_object_notify_state_change.
+ *
  * Returns: %TRUE if @type was the state type is in @set.
  **/
 gboolean
diff --git a/docs/atk-sections.txt b/docs/atk-sections.txt
index f83bd50..1224f31 100644
--- a/docs/atk-sections.txt
+++ b/docs/atk-sections.txt
@@ -211,7 +211,6 @@ ATK_IS_IMPLEMENTOR
 ATK_IMPLEMENTOR
 ATK_TYPE_ROLE
 ATK_TYPE_LAYER
-AtkStateSet
 atk_implementor_get_type
 atk_object_get_type
 atk_role_get_type