Minor documentation clarifications and tweaks.

6 files changed, 82 insertions, 32 deletions

diff --git a/ChangeLog b/ChangeLog
index f9f7577..208b8aa 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,4 +1,17 @@
 2006-03-20 Bill Haneman <bill.haneman@sun.com>
+	
+	* atk/atkutil.h: Added missing info on AtkEventListener,
+	AtkEventListenerInit, and AtkKeySnoopFunc. bug #320911.
+
+	* atk/atkimage.h: Moved information about '-1' return values
+	to the corresponding parameters.  bug #320916.
+	
+	* atk/atkobject.c: Fixed some docs issues in comment blocks.
+
+	* docs/tmpl/atkobject.sgml: Clarify children-changed signal
+	params. bug #162410.
+	
+2006-03-20 Bill Haneman <bill.haneman@sun.com>
 
 	* atk/atkimage.c: Bug detected by Behdad Estafood
 	(atk_image_get_position): Allow for NULL-in params.
diff --git a/atk/atkimage.c b/atk/atkimage.c
index 1f69fbc..3566d67 100755
--- a/atk/atkimage.c
+++ b/atk/atkimage.c
@@ -68,12 +68,12 @@ atk_image_get_image_description (AtkImage *image)
 /**
  * atk_image_get_image_size:
  * @image: a #GObject instance that implements AtkImageIface
- * @width: filled with the image width
- * @height: filled with the image height
+ * @width: filled with the image width, or -1 if the value cannot be obtained.
+ * @height: filled with the image height, or -1 if the value cannot be obtained.
  *
  * Get the width and height in pixels for the specified image.
  * The values of @width and @height are returned as -1 if the
- * values cannot be obtained.
+ * values cannot be obtained (for instance, if the object is not onscreen).
  **/
 void
 atk_image_get_image_size (AtkImage *image, 
@@ -189,6 +189,7 @@ atk_image_get_image_position (AtkImage *image,
 
 /** 
  * Returns a string corresponding to the POSIX LC_MESSAGES locale used by the image description, or NULL if the image does not specify a locale. 
+ * @image: An #AtkImage
  * @Since ATK 1.12
  */
 G_CONST_RETURN gchar* 
diff --git a/atk/atkobject.c b/atk/atkobject.c
index 80dca6f..f896b51 100755
--- a/atk/atkobject.c
+++ b/atk/atkobject.c
@@ -1008,17 +1008,17 @@ atk_object_notify_state_change (AtkObject *accessible,
  * Returns: a reference to an object's #AtkObject implementation
  */
 AtkObject *
-atk_implementor_ref_accessible (AtkImplementor *object)
+atk_implementor_ref_accessible (AtkImplementor *implementor)
 {
   AtkImplementorIface *iface;
   AtkObject           *accessible = NULL;
 
-  g_return_val_if_fail (ATK_IS_IMPLEMENTOR (object), NULL);
+  g_return_val_if_fail (ATK_IS_IMPLEMENTOR (implementor), NULL);
 
-  iface = ATK_IMPLEMENTOR_GET_IFACE (object);
+  iface = ATK_IMPLEMENTOR_GET_IFACE (implementor);
 
   if (iface != NULL) 
-    accessible =  iface->ref_accessible (object);
+    accessible =  iface->ref_accessible (implementor);
 
   g_return_val_if_fail ((accessible != NULL), NULL);
 
@@ -1027,6 +1027,9 @@ atk_implementor_ref_accessible (AtkImplementor *object)
 
     	
 /**
+ * atk_object_get_attributes:
+ *
+ * @accessible: An #AtkObject.
  * Get a list of properties applied to this object as a whole, as an #AtkAttributeSet consisting of 
  * name-value pairs. As such these attributes may be considered weakly-typed properties or annotations, 
  * as distinct from strongly-typed object data available via other get/set methods.
diff --git a/atk/atkutil.h b/atk/atkutil.h
index 042d610..1dbfcf3 100755
--- a/atk/atkutil.h
+++ b/atk/atkutil.h
@@ -41,12 +41,46 @@ typedef struct _AtkUtilClass AtkUtilClass;
 typedef struct _AtkKeyEventStruct AtkKeyEventStruct;
 #endif
 
-/*
- * A focus tracker is a function which is called when an object 
- * receives focus.
- */
-typedef void  (*AtkEventListener) (AtkObject*);
+/**
+ * AtkEventListener: 
+ * @obj: An #AtkObject instance for whom the callback will be called when
+ * the specified event (e.g. 'focus:') takes place.
+ *
+ * A function which is called when an object emits a matching event,
+ * as used in #atk_add_focus_tracker.
+ * Currently the only events for which object-specific handlers are
+ * supported are events of type "focus:".  Most clients of ATK will prefer to 
+ * attach signal handlers for the various ATK signals instead.
+ *
+ * @see: atk_add_focus_tracker.
+ **/
+typedef void  (*AtkEventListener) (AtkObject* obj);
+/**
+ * AtkEventListenerInit:
+ *
+ * An #AtkEventListenerInit function is a special function that is
+ * called in order to initialize the per-object event registration system
+ * used by #AtkEventListener, if any preparation is required.  
+ *
+ * @see: atk_focus_tracker_init.
+ **/
 typedef void  (*AtkEventListenerInit) (void);
+/**
+ * AtkKeySnoopFunc:
+ * @event: an AtkKeyEventStruct containing information about the key event for which
+ * notification is being given.
+ * @func_data: a block of data which will be passed to the event listener, on notification.
+ *
+ * An #AtkKeySnoopFunc is a type of callback which is called whenever a key event occurs, 
+ * if registered via atk_add_key_event_listener.  It allows for pre-emptive 
+ * interception of key events via the return code as described below.
+ *
+ * Returns: TRUE (nonzero) if the event emission should be stopped and the event 
+ * discarded without being passed to the normal GUI recipient; FALSE (zero) if the 
+ * event dispatch to the client application should proceed as normal.
+ *
+ * @see: atk_add_key_event_listener.
+ **/
 typedef gint  (*AtkKeySnoopFunc)  (AtkKeyEventStruct *event,
 				   gpointer func_data);
 
@@ -122,12 +156,16 @@ guint    atk_add_focus_tracker     (AtkEventListener      focus_tracker);
 void     atk_remove_focus_tracker  (guint                tracker_id);
 
 /*
+ * atk_focus_tracker_init:
+ * @init: An #AtkEventListenerInit function to be called
+ * prior to any focus-tracking requests.
+ *
  * Specifies the function to be called for focus tracker initialization.
  * removal. This function should be called by an implementation of the
  * ATK interface if any specific work needs to be done to enable
  * focus tracking.
  */
-void     atk_focus_tracker_init    (AtkEventListenerInit  add_function);
+void     atk_focus_tracker_init    (AtkEventListenerInit  init);
 
 /*
  * Cause the focus tracker functions which have been specified to be
diff --git a/docs/tmpl/atkobject.sgml b/docs/tmpl/atkobject.sgml
index dc03dd3..4a0835a 100644
--- a/docs/tmpl/atkobject.sgml
+++ b/docs/tmpl/atkobject.sgml
@@ -60,7 +60,7 @@ removed form an object. It supports two details: "add" and "remove"
 
 @atkobject: the object which received the signal.
 @arg1: The index of the added or removed child
-@arg2: The child which was added or removed
+@arg2: A gpointer to the child AtkObject which was added or removed
 
 <!-- ##### SIGNAL AtkObject::focus-event ##### -->
 <para>
diff --git a/docs/tmpl/atkutil.sgml b/docs/tmpl/atkutil.sgml
index c715f41..08b2507 100644
--- a/docs/tmpl/atkutil.sgml
+++ b/docs/tmpl/atkutil.sgml
@@ -2,14 +2,13 @@
 AtkUtil
 
 <!-- ##### SECTION Short_Description ##### -->
-This is a utility class which supports the adding and removal of event listeners.
+A set of ATK utility functions for event and toolkit support.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-This is a utility class which supports the adding and removal of event 
-listeners. The adding and removing of the listeners must be done in the 
-same thread. The file also contains a number of utility functions.
-
+A set of ATK utility functions which are used to support event registration of
+various types, and obtaining the 'root' accessible of a process and
+information about the current ATK implementation and toolkit version.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -22,7 +21,6 @@ same thread. The file also contains a number of utility functions.
 
 <!-- ##### STRUCT AtkUtil ##### -->
 <para>
-The AtkObject structure should not be accessed directly.
 
 </para>
 
@@ -57,6 +55,8 @@ The AtkObject structure should not be accessed directly.
 
 </para>
 
+@init: 
+<!-- # Unused Parameters # -->
 @add_function: 
 
 
@@ -70,19 +70,14 @@ The AtkObject structure should not be accessed directly.
 
 <!-- ##### USER_FUNCTION AtkEventListener ##### -->
 <para>
-An AtkEventListener is user specified function which is called when an event,
-such as receiving focus, occurs. The parameter of the AtkEventListener is the
-AtkObject on which the event occurred.
+
 </para>
 
-@Param1: an #AtkObject
+@obj: 
 
 
 <!-- ##### USER_FUNCTION AtkEventListenerInit ##### -->
 <para>
-An AtkEventListenerInit is an initialization function in an implementation 
-of the ATK interface used to perform implementation-specific initialization
-when enabling focus tracking.
 
 </para>
 
@@ -108,7 +103,7 @@ when enabling focus tracking.
 
 <!-- ##### STRUCT AtkKeyEventStruct ##### -->
 <para>
-The AtkKeyEventStruct describes a keyboard event.
+
 </para>
 
 @type: 
@@ -130,12 +125,12 @@ The AtkKeyEventStruct describes a keyboard event.
 
 <!-- ##### USER_FUNCTION AtkKeySnoopFunc ##### -->
 <para>
-An AtkKeySnoopFunc is a function which is called when a keyboard event occurs.
+
 </para>
 
-@event: keyboard event
-@func_data: a data gpointer for the function
-@Returns: return code
+@event: 
+@func_data: 
+@Returns: 
 
 
 <!-- ##### FUNCTION atk_add_key_event_listener ##### -->