atkobject: improve documentation for AtkObject::property-change

https://bugzilla.gnome.org/show_bug.cgi?id=644747

2 files changed, 19 insertions, 15 deletions

diff --git a/atk/atkobject.c b/atk/atkobject.c
index b3d4fb4..cadf734 100755
--- a/atk/atkobject.c
+++ b/atk/atkobject.c
@@ -628,11 +628,22 @@ atk_object_class_init (AtkObjectClass *klass)
   /**
    * AtkObject::property-change:
    * @atkobject: the object which received the signal.
-   * @arg1: The new value of the property which changed.
+   * @arg1: an #AtkPropertyValues containing the new value of the
+   *   property which changed.
    *
    * The signal "property-change" is emitted when an object's property
-   * value changes. The detail identifies the name of the property
-   * whose value has changed.
+   * value changes. @arg1 contains an #AtkPropertyValues with the name
+   * and the new value of the property whose value has changed. Note
+   * that, as with GObject notify, getting this signal does not
+   * guarantee that the value of the property has actually changed; it
+   * may also be emitted when the setter of the property is called to
+   * reinstate the previous value.
+   *
+   * Toolkit implementor note: ATK implementors should use
+   * g_object_notify() to emit property-changed
+   * notifications. #AtkObject::property-changed is needed by the
+   * implementation of atk_add_global_event_listener() because GObject
+   * notify doesn't support emission hooks.
    */
   atk_object_signals[PROPERTY_CHANGE] =
     g_signal_new ("property_change",
diff --git a/atk/atkobject.h b/atk/atkobject.h
index 781c317..f0cb898 100755
--- a/atk/atkobject.h
+++ b/atk/atkobject.h
@@ -420,20 +420,13 @@ typedef struct _AtkStateSet               AtkStateSet;
 
 /**
  * AtkPropertyValues:
- * @property_name: The name of the ATK property which is being presented or which has been changed.
- * @old_value: The old property value, NULL; in some contexts this value is undefined (see note below).
+ * @property_name: The name of the ATK property which has changed.
+ * @old_value: NULL. This field is not used anymore.
  * @new_value: The new value of the named property.
  *
- * Note: for most properties the old_value field of #AtkPropertyValues
- * will not contain a valid value.
- *
- * Currently, the only property for which old_value is used is
- * accessible-state; for instance if there is a focus state the
- * property change handler will be called for the object which lost the focus
- * with the old_value containing an #AtkState value corresponding to focused
- * and the property change handler will be called for the object which
- * received the focus with the new_value containing an #AtkState value
- * corresponding to focused.
+ * Note: @old_value field of #AtkPropertyValues will not contain a
+ * valid value. This is a field defined with the purpose of contain
+ * the previous value of the property, but is not used anymore.
  *
  **/
 struct _AtkPropertyValues