Updated gtk-doc comment blocks for Oisin Boydell

19 files changed, 381 insertions, 397 deletions

diff --git a/atk/atkaction.c b/atk/atkaction.c
index 8634a26..de941f3 100755
--- a/atk/atkaction.c
+++ b/atk/atkaction.c
@@ -41,16 +41,10 @@ atk_action_get_type ()
 
 /**
  * atk_action_do_action:
- * @action: a GObject instance that implements AtkActionIface
- * @i: a %gint indicating the action to be performed 
- *
- * This function would be called by an application with
- * the argument being a AtkObject object cast to (AtkAction).
- * The function will just check that * the corresponding
- * function pointer is not NULL and will call it.
- * The "real" implementation of the function for accessible will be
- * provided in a support library
+ * @action: a #GObject instance that implements AtkActionIface
+ * @i: the action to be performed 
  *
+ * Perform the specified action on the object
  **/
 void
 atk_action_do_action (AtkAction *obj,
@@ -69,18 +63,14 @@ atk_action_do_action (AtkAction *obj,
 
 /**
  * atk_action_get_n_actions:
- * @action: a GObject instance that implements AtkActionIface
- *
+ * @action: a #GObject instance that implements AtkActionIface
  * 
- * This function would be called by an application with
- * the argument being a AtkObject object cast to (AtkAction).
- * The function will just check that * the corresponding
- * function pointer is not NULL and will call it.
- * The "real" implementation of the function for accessible will be
- * provided in a support library
+ * Gets the number of accessible actions available on the object.
+ * If there are more than one, the first one is considered the
+ * "default" action of the object.
  *
- * Returns a %gint representing the number of actions , or 0
- * if value does not implement this interface.
+ * Returns: a the number of actions , or 0
+ * if @action does not implement this interface.
  **/
 gint
 atk_action_get_n_actions  (AtkAction *obj)
@@ -100,19 +90,13 @@ atk_action_get_n_actions  (AtkAction *obj)
 
 /**
  * atk_action_get_description:
- * @action: a GObject instance that implements AtkActionIface
+ * @action: a #GObject instance that implements AtkActionIface
  * @i: a %gint indicating the action
  *
- * 
- * This function would be called by an application with
- * the argument being a AtkObject object cast to (AtkAction).
- * The function will just check that * the corresponding
- * function pointer is not NULL and will call it.
- * The "real" implementation of the function for accessible will be
- * provided in a support library
+ * Returns a description of the specified action of the object
  *
- * Returns a #gchar representing the description, or %NULL
- * if value does not implement this interface.
+ * Returns a description string, or %NULL
+ * if @action does not implement this interface.
  **/
 G_CONST_RETURN gchar*
 atk_action_get_description (AtkAction *obj,
@@ -133,18 +117,12 @@ atk_action_get_description (AtkAction *obj,
 
 /**
  * atk_action_get_keybinding:
- * @action: a GObject instance that implements AtkActionIface
+ * @action: a #GObject instance that implements AtkActionIface
  * @i: a %gint indicating the action
  *
- * 
- * This function would be called by an application with
- * the argument being a AtkObject object cast to (AtkAction).
- * The function will just check that * the corresponding
- * function pointer is not NULL and will call it.
- * The "real" implementation of the function for accessible will be
- * provided in a support library
+ * Returns a keybinding associated with this action, if one exists.
  *
- * Returns a #gchar representing the keybinding, or %NULL
+ * Returns a string representing the keybinding, or %NULL
  * if there is no keybinding for this action.
  *
  **/
diff --git a/atk/atkcomponent.c b/atk/atkcomponent.c
index 507a723..ecf45a3 100755
--- a/atk/atkcomponent.c
+++ b/atk/atkcomponent.c
@@ -45,12 +45,12 @@ atk_component_get_type ()
 }
 
 /**
- *atk_component_add_focus_handler:
- *@component: The #AtkComponent to attach the @handler to
- *@handler: The #AtkFocusHandler to be attached to @component
+ * atk_component_add_focus_handler:
+ * @component: The #AtkComponent to attach the @handler to
+ * @handler: The #AtkFocusHandler to be attached to @component
  *
  * Add the specified handler to the set of functions to be called 
- * when this object receives focus (in or out) events.
+ * when this object receives focus events (in or out).
  *
  * Returns:
  **/
@@ -71,13 +71,14 @@ atk_component_add_focus_handler (AtkComponent    *component,
 }
 
 /**
- *atk_component_remove_focus_handler:
- *@component: the #AtkComponent to remove the focus handler from
- *@handler_id: the handler id of the focus handler to be removed
+ * atk_component_remove_focus_handler:
+ * @component: the #AtkComponent to remove the focus handler from
+ * @handler_id: the handler id of the focus handler to be removed
  * from @component
  *
  * Remove the handler specified by @handler_id from the list of
- * functions to be executed when this object receives focus (in or out)
+ * functions to be executed when this object receives focus events 
+ * (in or out).
  **/
 void
 atk_component_remove_focus_handler (AtkComponent    *component,
@@ -94,17 +95,17 @@ atk_component_remove_focus_handler (AtkComponent    *component,
 }
 
 /**
- *atk_component_contains:
- *@component: the #AtkComponent
- *@x: x coordinate relative to the coordinate system of @component
- *@y: y coordinate relative to the coordinate system of @component
+ * atk_component_contains:
+ * @component: the #AtkComponent
+ * @x: x coordinate relative to the coordinate system of @component
+ * @y: y coordinate relative to the coordinate system of @component
  *
  * Checks whether the specified point is within the extent of the @component,
- * the points x and y coordinates are defined to be relative to the 
+ * the x and y coordinates are defined to be relative to the 
  * coordinate system of the @component.
  *
- * Returns: a #gboolean indicating whether the specified point is within
- *  the extent of the @component
+ * Returns: %TRUE or %FALSE indicating whether the specified point is within
+ * the extent of the @component or not
  **/
 gboolean
 atk_component_contains (AtkComponent    *component,
@@ -124,16 +125,15 @@ atk_component_contains (AtkComponent    *component,
 }
 
 /**
- *atk_component_get_accessible_at_point:
- *@component: the #AtkComponent
- *@x: local x coordinate
- *@y: local y coordinate
+ * atk_component_get_accessible_at_point:
+ * @component: the #AtkComponent
+ * @x: local x coordinate
+ * @y: local y coordinate
  *
  * Gets the accessible child, if one exists, contained at the local
  * coordinate point specified by @x and @y.
  *
- *Returns: the accessible child, if one exists, contained at the local
- * coordinate point specified by @x and @y.
+ * Returns: the accessible child, if one exists
  **/
 AtkObject*
 atk_component_get_accessible_at_point (AtkComponent    *component,
@@ -158,12 +158,12 @@ atk_component_get_accessible_at_point (AtkComponent    *component,
 }
 
 /**
- *atk_component_get_extents:
- *@component: an #AtkComponent
- *@x: address of #gint to put x coordinate
- *@y: address of #gint to put y coordinate
- *@width: address of #gint to put width
- *@height: address of #gint to put height
+ * atk_component_get_extents:
+ * @component: an #AtkComponent
+ * @x: address of #gint to put x coordinate
+ * @y: address of #gint to put y coordinate
+ * @width: address of #gint to put width
+ * @height: address of #gint to put height
  *
  * Gets the rectangle which gives the extent of the @component.
  *
@@ -186,10 +186,10 @@ atk_component_get_extents    (AtkComponent    *component,
 }
 
 /**
- *atk_component_get_position:
- *@component: an #AtkComponent
- *@x: address of #gint to put x coordinate position
- *@y: address of #gint to put y coordinate position
+ * atk_component_get_position:
+ * @component: an #AtkComponent
+ * @x: address of #gint to put x coordinate position
+ * @y: address of #gint to put y coordinate position
  *
  * Gets the position of @component relative to the parent in the form of 
  * a point specifying @component's top-left corner in the screen's
@@ -211,10 +211,10 @@ atk_component_get_position   (AtkComponent    *component,
 }
 
 /**
- *atk_component_get_position_on_screen:
- *@component: an #AtkComponent
- *@x: address of #gint to put x coordinate position
- *@y: address of #gint to put y coordinate position
+ * atk_component_get_position_on_screen:
+ * @component: an #AtkComponent
+ * @x: address of #gint to put x coordinate position
+ * @y: address of #gint to put y coordinate position
  *
  * Gets the position of the @component on the screen
  **/
@@ -234,12 +234,12 @@ atk_component_get_position_on_screen (AtkComponent    *component,
 }
 
 /**
- *atk_component_get_size:
- *@component: an #AtkComponent
- *@width: address of #gint to put width of @component
- *@height: address of #gint to put height of @component
+ * atk_component_get_size:
+ * @component: an #AtkComponent
+ * @width: address of #gint to put width of @component
+ * @height: address of #gint to put height of @component
  *
- * Gets the size of the @component.
+ * Gets the size of the @component in terms of width and height.
  **/
 void
 atk_component_get_size       (AtkComponent    *component,
@@ -257,8 +257,8 @@ atk_component_get_size       (AtkComponent    *component,
 }
 
 /**
- *atk_component_grab_focus:
- *@component: an #AtkComponent
+ * atk_component_grab_focus:
+ * @component: an #AtkComponent
  *
  * Grabs focus for this @component
  **/
@@ -276,12 +276,12 @@ atk_component_grab_focus (AtkComponent    *component)
 }
 
 /**
- *atk_component_set_extents:
- *@component: an #AtkComponent
- *@x: x coordinate to set for @component
- *@y: y coordinate to set for @component
- *@width: width to set for @component
- *@height: height to set for @component
+ * atk_component_set_extents:
+ * @component: an #AtkComponent
+ * @x: x coordinate
+ * @y: y coordinate
+ * @width: width to set for @component
+ * @height: height to set for @component
  *
  * Sets the extents of @component
  **/
@@ -303,10 +303,10 @@ atk_component_set_extents   (AtkComponent    *component,
 }
 
 /**
- *atk_component_set_position:
- *@component: an #AtkComponent
- *@x: x coordinate
- *@y: y coordinate
+ * atk_component_set_position:
+ * @component: an #AtkComponent
+ * @x: x coordinate
+ * @y: y coordinate
  *
  * Sets the postition of @component
  **/
@@ -326,12 +326,12 @@ atk_component_set_position   (AtkComponent    *component,
 }
 
 /**
- *atk_component_set_size:
- *@component: an #AtkComponent
- *@width: width to set for @component
- *@height: height to set for @component
+ * atk_component_set_size:
+ * @component: an #AtkComponent
+ * @width: width to set for @component
+ * @height: height to set for @component
  *
- * Set the size of the @component
+ * Set the size of the @component in terms of width and height
  **/
 void
 atk_component_set_size       (AtkComponent    *component,
diff --git a/atk/atkeditabletext.c b/atk/atkeditabletext.c
index e5c113c..e80c6b3 100755
--- a/atk/atkeditabletext.c
+++ b/atk/atkeditabletext.c
@@ -49,12 +49,15 @@ atk_editable_text_get_type ()
 
 
 /**
- *atk_editable_text_select_text:
- *@text: an #AtkEditableText
- *@start_pos: start position
- *@end_pos: end position
+ * atk_editable_text_select_text:
+ * @text: an #AtkEditableText
+ * @start_pos: start position
+ * @end_pos: end position
  *
- *Select text between @start_pos and @end_pos
+ * Select text between @start_pos and @end_pos. The characters that are selected
+ * are those characters at positions from @start_pos up to, but not including
+ * @end_pos. If @end_pos is negative, then the characters selected 
+ * will be those characters from start_pos to the end of the text.
  **/
 void 
 atk_editable_text_select_text (AtkEditableText  *text,
@@ -73,13 +76,17 @@ atk_editable_text_select_text (AtkEditableText  *text,
 }
 
 /**
- *atk_editable_text_set_attributes:
- *@text: an #AtkEditableText
- *@start_pos: start position
- *@end_pos: end position
- *@attributes: a #PangoAttrList to set for @text
+ * atk_editable_text_set_attributes:
+ * @text: an #AtkEditableText
+ * @start_pos: start position
+ * @end_pos: end position
+ * @attributes: a #PangoAttrList to set for text between @start_pos and @end_pos
  *
- *Set attributes for text between @start_pos and @end_pos
+ * Set attributes for text between @start_pos and @end_pos.  The characters
+ * whose attributes are set are those characters at positions from @start_pos
+ * up to, but not including @end_pos. If @end_pos is negative, then the
+ * characters selected will be those characters from start_pos to 
+ * the end of the text.
  **/
 void 
 atk_editable_text_set_attributes (AtkEditableText  *text,
@@ -99,11 +106,11 @@ atk_editable_text_set_attributes (AtkEditableText  *text,
 }
 
 /**
- *atk_editable_text_set_text_contents:
- *@text: an #AtkEditableText
- *@string: string to set for text contents of @text
+ * atk_editable_text_set_text_contents:
+ * @text: an #AtkEditableText
+ * @string: string to set for text contents of @text
  *
- *Set text contents of @text
+ * Set text contents of @text
  **/
 void 
 atk_editable_text_set_text_contents (AtkEditableText  *text,
@@ -121,14 +128,15 @@ atk_editable_text_set_text_contents (AtkEditableText  *text,
 }
 
 /**
- *atk_editable_text_insert_text:
- *@text: an #AtkEditableText
- *@string: a #gchar string to insert
- *@length: number of characters to insert @string
- *@position: position at which to insert @string
+ * atk_editable_text_insert_text:
+ * @text: an #AtkEditableText
+ * @string: the text to insert
+ * @length: the length of text to insert, in bytes
+ * @position: The caller initializes this to 
+ * the position at which to insert the text. After the call it
+ * points at the position after the newly inserted text.
  *
- *Insert @length characters of @string into text contents
- * of @text at position @position 
+ * Insert text at a given position
  **/
 void 
 atk_editable_text_insert_text (AtkEditableText  *text,
@@ -148,12 +156,13 @@ atk_editable_text_insert_text (AtkEditableText  *text,
 }
 
 /**
- *atk_editable_text_copy_text:
- *@text: an #AtkEditableText
- *@start_pos: start position
- *@end_pos: end position
+ * atk_editable_text_copy_text:
+ * @text: an #AtkEditableText
+ * @start_pos: start position
+ * @end_pos: end position
  *
- * Copy text between @start_pos and @end_pos
+ * Copy text from @start_pos up to, but not including @end_pos 
+ * to the clipboard.
  **/
 void 
 atk_editable_text_copy_text (AtkEditableText  *text,
@@ -172,12 +181,13 @@ atk_editable_text_copy_text (AtkEditableText  *text,
 }
 
 /**
- *atk_editable_text_cut_text:
- *@text: an #AtkEditableText
- *@start_pos: start position
- *@end_pos: end position
+ * atk_editable_text_cut_text:
+ * @text: an #AtkEditableText
+ * @start_pos: start position
+ * @end_pos: end position
  *
- * Cut text between @start_pos and @end_pos
+ * Copy text from @start_pos up to, but not including @end_pos
+ * to the clipboard and then delete from the widget.
  **/
 void 
 atk_editable_text_cut_text  (AtkEditableText  *text,
@@ -196,12 +206,12 @@ atk_editable_text_cut_text  (AtkEditableText  *text,
 }
 
 /**
- *atk_editable_text_delete_text:
- *@text: an #AtkEditableText
- *@start_pos: start position
- *@end_pos: end position
+ * atk_editable_text_delete_text:
+ * @text: an #AtkEditableText
+ * @start_pos: start position
+ * @end_pos: end position
  *
- * Delete text between @start_pos and @end_pos
+ * Delete text @start_pos up to, but not including @end_pos
  **/
 void 
 atk_editable_text_delete_text (AtkEditableText  *text,
@@ -220,11 +230,11 @@ atk_editable_text_delete_text (AtkEditableText  *text,
 }
 
 /**
- *atk_editable_text_paste_text:
- *@text: an #AtkEditableText
- *@position: position to paste
+ * atk_editable_text_paste_text:
+ * @text: an #AtkEditableText
+ * @position: position to paste
  *
- * Paste text at @position 
+ * Paste text from clipboard to specified @position 
  **/
 void 
 atk_editable_text_paste_text (AtkEditableText  *text,
diff --git a/atk/atkhypertext.c b/atk/atkhypertext.c
index b103a81..f78639d 100755
--- a/atk/atkhypertext.c
+++ b/atk/atkhypertext.c
@@ -51,10 +51,6 @@ atk_hypertext_get_type ()
   return type;
 }
 
-
-/*
- */
-
 static void
 atk_hypertext_interface_init (AtkHypertextIfaceClass *klass)
 {
@@ -62,14 +58,14 @@ atk_hypertext_interface_init (AtkHypertextIfaceClass *klass)
 }
 
 /**
- *atk_hypertext_get_link:
- *@hypertext: an #AtkHypertext
- *@link_index: the index of the link to be returned
+ * atk_hypertext_get_link:
+ * @hypertext: an #AtkHypertext
+ * @link_index: an integer specifying the desired link
  *
  * Gets the link in this hypertext document at index 
  * @link_index
  *
- *Returns: the link in this hypertext document at
+ * Returns: the link in this hypertext document at
  * index @link_index
  **/
 AtkHyperLink* 
@@ -90,12 +86,12 @@ atk_hypertext_get_link (AtkHypertext  *hypertext,
 }
 
 /**
- *atk_hypertext_get_n_links:
- *@hypertext: an #AtkHypertext
+ * atk_hypertext_get_n_links:
+ * @hypertext: an #AtkHypertext
  *
  * Gets the number of links within this hypertext document.
  *
- *Returns: the number of links within this hypertext document
+ * Returns: the number of links within this hypertext document
  **/
 gint 
 atk_hypertext_get_n_links (AtkHypertext  *hypertext)
@@ -114,17 +110,15 @@ atk_hypertext_get_n_links (AtkHypertext  *hypertext)
 }
 
 /**
- *atk_hypertext_get_link_index:
- *@hypertext: an #AtkHypertext
- *@char_index: a character index
+ * atk_hypertext_get_link_index:
+ * @hypertext: an #AtkHypertext
+ * @char_index: a character index
  *
  * Gets the index into the array of hyperlinks that is associated with
- * @char_index character index, or -1 if there is no hyperlink associated with
- * @char_index.
+ * the character specified by @cahr_index, or -1 if there is no hyperlink
+ * associated with this character.
  *
- * Returns: the index into the array of hyperlinks that is associated with
- * @char_index character index, or -1 if there is no hyperlink associated with
- * @char_index.
+ * Returns: an index into the array of hyperlinks in @hypertext
  **/
 gint 
 atk_hypertext_get_link_index (AtkHypertext  *hypertext,
diff --git a/atk/atkimage.c b/atk/atkimage.c
index 40892bb..81a3dd7 100755
--- a/atk/atkimage.c
+++ b/atk/atkimage.c
@@ -41,12 +41,11 @@ atk_image_get_type ()
 
 /**
  * atk_image_get_storage_type:
- * @image: a GObject instance that implements AtkImageIface
+ * @image: a #GObject instance that implements AtkImageIface
  *
  * Gets the type of representation being used to store image data
- * [maybe this method will be replaced, watch this space.]
  *
- * Returns: a AtkStorageType representing the image storage type
+ * Returns: an #AtkStorageType representing the image storage type
  **/
 AtkImageType
 atk_image_get_storage_type (AtkImage *obj)
@@ -70,11 +69,11 @@ atk_image_get_storage_type (AtkImage *obj)
 
 /**
  * atk_image_get_image_description:
- * @image: a GObject instance that implements AtkImageIface
+ * @image: a #GObject instance that implements AtkImageIface
  *
  * Get a textual description of this image.
  *
- * Returns: a gchar* representing the image description
+ * Returns: a string representing the image description
  **/
 G_CONST_RETURN gchar*
 atk_image_get_image_description (AtkImage *obj)
@@ -98,11 +97,11 @@ atk_image_get_image_description (AtkImage *obj)
 
 /**
  * atk_image_get_image_height:
- * @image: a GObject instance that implements AtkImageIface
+ * @image: a #GObject instance that implements AtkImageIface
  *
  * Get the height, in pixels/screen coords, of this image.
  *
- * Returns: a gint representing the image height in pixel coords
+ * Returns: an integer representing the image height in pixel coords
  **/
 gint
 atk_image_get_image_height (AtkImage *obj)
@@ -126,11 +125,11 @@ atk_image_get_image_height (AtkImage *obj)
 
 /**
  * atk_image_get_image_width:
- * @image: a GObject instance that implements AtkImageIface
+ * @image: a #GObject instance that implements AtkImageIface
  *
  * Get the width, in pixel/screen coords, of this image.
  *
- * Returns: a gint representing the image width
+ * Returns: an integer representing the image width
  **/
 gint
 atk_image_get_image_width (AtkImage *obj)
@@ -154,8 +153,8 @@ atk_image_get_image_width (AtkImage *obj)
 
 /**
  * atk_image_set_image_description:
- * @image: a GObject instance that implements AtkImageIface
- * @description: a #gchar desciption to set for @image
+ * @image: a #GObject instance that implements AtkImageIface
+ * @description: a string desciption to set for @image
  *
  * Sets the textual description for this image.
  *
diff --git a/atk/atknoopobject.c b/atk/atknoopobject.c
index cc87360..bbb2999 100644
--- a/atk/atknoopobject.c
+++ b/atk/atknoopobject.c
@@ -132,13 +132,13 @@ atk_no_op_object_class_init (AtkNoOpObjectClass *klass)
 }
 
 /**
- *atk_no_op_object_new:
- *@obj: a #GObject
+ * atk_no_op_object_new:
+ * @obj: a #GObject
  *
- *Provides a default (non-functioning stub) #AtkObject.
- *Application maintainers should not use this method. 
+ * Provides a default (non-functioning stub) #AtkObject.
+ * Application maintainers should not use this method. 
  *
- *Returns: a default (non-functioning stub) #AtkObject
+ * Returns: a default (non-functioning stub) #AtkObject
  **/
 AtkObject*
 atk_no_op_object_new (GObject *obj)
diff --git a/atk/atknoopobjectfactory.c b/atk/atknoopobjectfactory.c
index 28c3965..5a484f4 100755
--- a/atk/atknoopobjectfactory.c
+++ b/atk/atknoopobjectfactory.c
@@ -68,12 +68,12 @@ atk_no_op_object_factory_class_init (AtkNoOpObjectFactoryClass *klass)
 }
 
 /**
- *atk_no_op_object_factory_new:
+ * atk_no_op_object_factory_new:
  *
- *Creates an instance of an #AtkObjectFactory which generates primitive
- *(non-functioning) #AtkObjects. 
+ * Creates an instance of an #AtkObjectFactory which generates primitive
+ * (non-functioning) #AtkObjects. 
  *
- *Returns: an instance of an #AtkObjectFactory
+ * Returns: an instance of an #AtkObjectFactory
  **/
 AtkObjectFactory* 
 atk_no_op_object_factory_new ()
diff --git a/atk/atkobject.c b/atk/atkobject.c
index c3f69da..e6a1128 100755
--- a/atk/atkobject.c
+++ b/atk/atkobject.c
@@ -198,11 +198,6 @@ atk_object_init  (AtkObject        *accessible,
 {
 }
 
-/**
- *atk_implementor_get_type:
- *
- *Returns: a #GType
- **/
 GType
 atk_implementor_get_type (void)
 {
@@ -225,7 +220,7 @@ atk_implementor_get_type (void)
 
 /**
  * atk_object_get_name:
- * @accessible: a #AtkObject
+ * @accessible: an #AtkObject
  *
  * Gets the accessible name of the accessible
  *
@@ -248,11 +243,12 @@ atk_object_get_name (AtkObject *accessible)
 
 /**
  * atk_object_get_description:
- * @accessible: a #AtkObject
+ * @accessible: an #AtkObject
  *
  * Gets the accessible description of the accessible
  *
- * Returns: a character string representing the accessible description of the accessible.
+ * Returns: a character string representing the accessible description
+ * of the accessible.
  *
  **/
 G_CONST_RETURN gchar*
@@ -272,11 +268,11 @@ atk_object_get_description (AtkObject *accessible)
 
 /**
  * atk_object_get_parent:
- * @accessible: a #AtkObject
+ * @accessible: an #AtkObject
  *
- * Gets the accessible description of the accessible
+ * Gets the accessible parent of the accessible
  *
- * Returns: a #AtkObject representing the accessible parent of the accessible.
+ * Returns: a #AtkObject representing the accessible parent of the accessible
  **/
 AtkObject*
 atk_object_get_parent (AtkObject *accessible)
@@ -295,11 +291,12 @@ atk_object_get_parent (AtkObject *accessible)
 
 /**
  * atk_object_get_n_accessible_children:
- * @accessible: a #AtkObject
+ * @accessible: an #AtkObject
  *
  * Gets the number of accessible children of the accessible
  *
- * Returns: a gint representing the number of accessible children of the accessible.
+ * Returns: an integer representing the number of accessible children
+ * of the accessible.
  **/
 gint
 atk_object_get_n_accessible_children (AtkObject *accessible)
@@ -318,14 +315,15 @@ atk_object_get_n_accessible_children (AtkObject *accessible)
 
 /**
  * atk_object_ref_accessible_child:
- * @accessible: a #AtkObject
+ * @accessible: an #AtkObject
  * @i: a gint representing the position of the child, starting from 0
  *
  * Gets a reference to the specified accessible child of the object.
  * The accessible children are 0-based so the first accessible child is
  * at index 0, the second at index 1 and so on.
  *
- * Returns: a #AtkObject representing the specified accessible child of the accessible.
+ * Returns: an #AtkObject representing the specified accessible child
+ * of the accessible.
  **/
 AtkObject*
 atk_object_ref_accessible_child (AtkObject   *accessible,
@@ -345,11 +343,11 @@ atk_object_ref_accessible_child (AtkObject   *accessible,
 
 /**
  * atk_object_ref_relation_set:
- * @accessible: a #AtkObject
+ * @accessible: an #AtkObject
  *
  * Gets the RelationSet associated with the object
  *
- * Returns: a #AtkRelationSet representing the relation set of the object.
+ * Returns: an #AtkRelationSet representing the relation set of the object.
  **/
 AtkRelationSet*
 atk_object_ref_relation_set (AtkObject *accessible)
@@ -370,7 +368,7 @@ atk_object_ref_relation_set (AtkObject *accessible)
  * atk_role_register:
  * @name: a character string describing the new role.
  *
- * Returns: a #AtkRole value for the new role.
+ * Returns: an #AtkRole for the new role.
  **/
 AtkRole
 atk_role_register (const gchar *name)
@@ -382,11 +380,11 @@ atk_role_register (const gchar *name)
 
 /**
  * atk_object_get_role:
- * @accessible: a #AtkObject
+ * @accessible: an #AtkObject
  *
  * Gets the role of the accessible
  *
- * Returns: a #AtkRole which is the role of the accessible
+ * Returns: an #AtkRole which is the role of the accessible
  **/
 AtkRole
 atk_object_get_role (AtkObject *accessible) {
@@ -404,12 +402,13 @@ atk_object_get_role (AtkObject *accessible) {
 
 /**
  * atk_object_ref_state_set:
- * @accessible: a #AtkObject
+ * @accessible: an #AtkObject
  *
  * Gets a reference to the state set of the accessible; the caller should
  * unreference it.
  *
- * Returns: a reference to a #AtkStateSet which is the state set of the accessible
+ * Returns: a reference to an #AtkStateSet which is the state
+ * set of the accessible
  **/
 AtkStateSet*
 atk_object_ref_state_set (AtkObject *accessible) {
@@ -427,12 +426,12 @@ atk_object_ref_state_set (AtkObject *accessible) {
 
 /**
  * atk_object_get_index_in_parent:
- * @accessible: a #AtkObject
+ * @accessible: an #AtkObject
  *
  * Gets the 0-based index of this accessible in its parent; returns -1 if the
  * accessible does not have an accessible parent.
  *
- * Returns: a gint which is the index of the accessible in its parent
+ * Returns: an integer which is the index of the accessible in its parent
  **/
 gint
 atk_object_get_index_in_parent (AtkObject *accessible)
@@ -451,7 +450,7 @@ atk_object_get_index_in_parent (AtkObject *accessible)
 
 /**
  * atk_object_set_name:
- * @accessible: a #AtkObject
+ * @accessible: an #AtkObject
  * @name: a character string to be set as the accessible name
  *
  * Sets the accessible name of the accessible
@@ -476,7 +475,7 @@ atk_object_set_name (AtkObject    *accessible,
 
 /**
  * atk_object_set_description:
- * @accessible: a #AtkObject
+ * @accessible: an #AtkObject
  * @description : a character string to be set as the accessible description
  *
  * Sets the accessible description of the accessible
@@ -501,8 +500,8 @@ atk_object_set_description (AtkObject   *accessible,
 
 /**
  * atk_object_set_parent:
- * @accessible: a #AtkObject
- * @parent : a #AtkObject to be set as the accessible parent
+ * @accessible: an #AtkObject
+ * @parent : an #AtkObject to be set as the accessible parent
  *
  * Sets the accessible parent of the accessible
  **/
@@ -522,8 +521,8 @@ atk_object_set_parent (AtkObject *accessible,
 
 /**
  * atk_object_set_role:
- * @accessible: a #AtkObject
- * @role : a #AtkRole to be set as the role
+ * @accessible: an #AtkObject
+ * @role : an #AtkRole to be set as the role
  *
  * Sets the role of the accessible
  **/
@@ -543,12 +542,13 @@ atk_object_set_role (AtkObject *accessible,
 
 /**
  * atk_object_connect_property_change_handler:
- * @accessible: a #AtkObject
- * @handler : a #AtkPropertyChangeHandler, a function to be called when a property changes its value
+ * @accessible: an #AtkObject
+ * @handler : a function to be called when a property changes its value
  *
  * Specifies a function to be called when a property changes value.
  *
- * Returns: a guint which is the handler id used in atk_object_remove_property_change_handler
+ * Returns: a #guint which is the handler id used in 
+ * atk_object_remove_property_change_handler()
  **/
 guint
 atk_object_connect_property_change_handler (AtkObject *accessible,
@@ -569,7 +569,7 @@ atk_object_connect_property_change_handler (AtkObject *accessible,
 
 /**
  * atk_object_remove_property_change_handler:
- * @accessible: a #AtkObject
+ * @accessible: an #AtkObject
  * @handler_id : a guint which identifies the handler to be removed.
  * 
  * Removes a property change handler.
@@ -590,14 +590,13 @@ atk_object_remove_property_change_handler  (AtkObject *accessible,
 
 /**
  * atk_implementor_ref_accessible:
- * @implementor: The GObject instance which should implement #AtkImplementorIface
+ * @implementor: The #GObject instance which should implement #AtkImplementorIface
  * if a non-null return value is required.
  * 
- * Returns a reference to an object's #AtkObject implementation, if
+ * Gets a reference to an object's #AtkObject implementation, if
  * the object implements #AtkObjectIface
  *
- * Returns: a reference to an object's #AtkObject implementation, if
- * the object implements #AtkObjectIface
+ * Returns: a reference to an object's #AtkObject implementation
  */
 AtkObject *
 atk_implementor_ref_accessible (AtkImplementor *object)
diff --git a/atk/atkobjectfactory.c b/atk/atkobjectfactory.c
index ecf6dcc..1193c78 100755
--- a/atk/atkobjectfactory.c
+++ b/atk/atkobjectfactory.c
@@ -57,16 +57,16 @@ atk_object_factory_class_init (AtkObjectFactoryClass *klass)
 }
 
 /**
- *atk_object_factory_create_accessible:
- *@factory: The #AtkObjectFactory associated with @obj's
- *object type
- *@obj: a #GObject 
+ * atk_object_factory_create_accessible:
+ * @factory: The #AtkObjectFactory associated with @obj's
+ * object type
+ * @obj: a #GObject 
  * 
- *Provides a #AtkObject that implements an accessability interface 
- *on behalf of @obj
+ * Provides an #AtkObject that implements an accessability interface 
+ * on behalf of @obj
  *
- *Returns: an #AtkObject that implements an accessability interface
- *on behalf of @obj
+ * Returns: an #AtkObject that implements an accessability interface
+ * on behalf of @obj
  **/
 AtkObject* 
 atk_object_factory_create_accessible (AtkObjectFactory *factory,
@@ -90,13 +90,13 @@ atk_object_factory_create_accessible (AtkObjectFactory *factory,
 } 
 
 /**
- *atk_object_factory_invalidate:
- *@factory: an #AtkObjectFactory
+ * atk_object_factory_invalidate:
+ * @factory: an #AtkObjectFactory to invalidate
  *
- *Inform @factory that it is no longer being used to create
+ * Inform @factory that it is no longer being used to create
  * accessables. When called, @factory may need to inform
- * #AtkObject's which it has created that they need to be re-instantiated.
- * Note: primarily used for runtime replacement of #AtkObjectFactory's
+ * #AtkObjects which it has created that they need to be re-instantiated.
+ * Note: primarily used for runtime replacement of #AtkObjectFactorys
  * in object registries.
  **/
 void 
diff --git a/atk/atkregistry.c b/atk/atkregistry.c
index 89f4a42..d85673e 100644
--- a/atk/atkregistry.c
+++ b/atk/atkregistry.c
@@ -117,13 +117,12 @@ atk_registry_finalize (GObject *instance)
 }
 
 /**
- *atk_registry_set_factory_type:
- *@registry: the #AtkRegistry in which to register the association
- * between an #AtkObjectFactory #GType and an #AtkObject @GType
- *@type: an #AtkObject #GType 
- *@factory_type: an #AtkObjectFactory #GType to associate with @type
+ * atk_registry_set_factory_type:
+ * @registry: the #AtkRegistry in which to register the type association
+ * @type: an #AtkObject type 
+ * @factory_type: an #AtkObjectFactory type to associate with @type
  *
- *Associate an #AtkObjectFactory subclass with a #GType. Note:
+ * Associate an #AtkObjectFactory subclass with a #GType. Note:
  * The associated @factory_type will thereafter be responsible for
  * the creation of new #AtkObject implementations for instances
  * of type @type.
@@ -164,16 +163,15 @@ atk_registry_set_factory_type (AtkRegistry *registry,
 }
 
 /**
- *atk_registry_get_factory_type:
- *@registry: an #AtkRegistry
- *@type: a #GType with which to look up the associated #AtkObjectFactory
+ * atk_registry_get_factory_type:
+ * @registry: an #AtkRegistry
+ * @type: a #GType with which to look up the associated #AtkObjectFactory
  * subclass
  *
- *Provides a GType indicating the #AtkObjectFactory subclass
+ * Provides a #GType indicating the #AtkObjectFactory subclass
  * associated with type @type
  *
- *Returns: a GType indicating the AtkObjectFactory subclass
- * associated with type @type
+ * Returns: a #GType associated with type @type
  **/
 GType
 atk_registry_get_factory_type (AtkRegistry *registry,
@@ -203,14 +201,14 @@ atk_registry_get_factory_type (AtkRegistry *registry,
 }
 
 /**
- *atk_registry_get_factory:
- *@registry: an #AtkRegistry
- *@type: a #GType with which to look up the associated #AtkObjectFactory
+ * atk_registry_get_factory:
+ * @registry: an #AtkRegistry
+ * @type: a #GType with which to look up the associated #AtkObjectFactory
  *
- *Returns an #AtkObjectFactory appropriate for creating #AtkObjects
+ * Gets an #AtkObjectFactory appropriate for creating #AtkObjects
  * of type @type.
  *
- *Returns: an #AtkObjectFactory appropriate for creating #AtkObjects
+ * Returns: an #AtkObjectFactory appropriate for creating #AtkObjects
  * of type @type.
  **/
 AtkObjectFactory*
@@ -253,15 +251,15 @@ atk_registry_get_factory (AtkRegistry *registry,
 /**
  *atk_get_default_registry:
  *
- *Return a default implementation of the #AtkObjectFactory/type
+ * Gets a default implementation of the #AtkObjectFactory/type
  * registry.
- *Note: For most toolkit maintainers, this will be the correct
+ * Note: For most toolkit maintainers, this will be the correct
  * registry for registering new #AtkObject factories. Following
  * a call to this function, maintainers may call atk_registry_set_factory_type()
  * to associate an #AtkObjectFactory subclass with the GType of objects
  * for whom accessability information will be provided.
  *
- *Returns: a default implementation of the #AtkObjectFactory/type
+ * Returns: a default implementation of the #AtkObjectFactory/type
  * registry
  **/
 AtkRegistry*
diff --git a/atk/atkrelation.c b/atk/atkrelation.c
index 53248e5..144523b 100755
--- a/atk/atkrelation.c
+++ b/atk/atkrelation.c
@@ -57,12 +57,12 @@ atk_relation_class_init (AtkRelationClass *klass)
 }
 
 /**
- *atk_relation_type_register:
- *@name: a #gchar name
+ * atk_relation_type_register:
+ * @name: a name string
  *
  * Associate @name with a new #AtkRelationType
  *
- *Returns: an #AtkRelationType associated with @name
+ * Returns: an #AtkRelationType associated with @name
  **/
 AtkRelationType
 atk_relation_type_register (const gchar *name)
@@ -73,10 +73,10 @@ atk_relation_type_register (const gchar *name)
 }
 
 /**
- *atk_relation_new:
- *@targets: an array of pointers to #AtkObjects  
- *@n_targets: number of #AtkObjects pointed to by @targets
- *@relationship: an #AtkRelationType with which to create the new
+ * atk_relation_new:
+ * @targets: an array of pointers to #AtkObjects  
+ * @n_targets: number of #AtkObjects pointed to by @targets
+ * @relationship: an #AtkRelationType with which to create the new
  *  #AtkRelation
  *
  * Create a new relation for the specified key and the specified list
@@ -113,12 +113,12 @@ atk_relation_new (AtkObject       **targets,
 }
 
 /**
- *atk_relation_get_relation_type:
- *@relation: an #AtkRelation 
+ * atk_relation_get_relation_type:
+ * @relation: an #AtkRelation 
  *
  * Gets the type of @relation
  *
- *Returns: the type of @relation
+ * Returns: the type of @relation
  **/
 AtkRelationType
 atk_relation_get_relation_type (AtkRelation *relation)
@@ -130,12 +130,12 @@ atk_relation_get_relation_type (AtkRelation *relation)
 }
 
 /**
- *atk_relation_get_target:
- *@relation: an #AtkRelation
+ * atk_relation_get_target:
+ * @relation: an #AtkRelation
  *
  * Gets the target list of @relation
  *
- *Returns: the target list of @relation
+ * Returns: the target list of @relation
  **/
 GPtrArray*
 atk_relation_get_target (AtkRelation *relation)
diff --git a/atk/atkrelationset.c b/atk/atkrelationset.c
index 89b8056..0724811 100755
--- a/atk/atkrelationset.c
+++ b/atk/atkrelationset.c
@@ -74,13 +74,14 @@ atk_relation_set_new (void)
 
 /**
  * atk_relation_set_contains:
- * @set: a #AtkRelationSet
- * @relationship: a #AtkRelationType
+ * @set: an #AtkRelationSet
+ * @relationship: an #AtkRelationType
  *
  * Determines whether the relation set contains a relation that matches the
  * specified type.
  *
- * Returns: %TRUE if @relationtype is the relationship type of a relation in @set.
+ * Returns: %TRUE if @relationship is the relationship type of a relation
+ * in @set, %FALSE otherwise
  **/
 gboolean
 atk_relation_set_contains (AtkRelationSet   *set,
@@ -107,11 +108,11 @@ atk_relation_set_contains (AtkRelationSet   *set,
 
 /**
  * atk_relation_set_remove:
- * @set: a #AtkRelationSet
- * @relation: a #AtkRelation
+ * @set: an #AtkRelationSet
+ * @relation: an #AtkRelation
  *
  * Removes a relation from the relation set.
- * This function unref's the AtkRelation so it will be deleted unless there
+ * This function unref's the #AtkRelation so it will be deleted unless there
  * is another reference to it.
  **/
 void
@@ -136,8 +137,8 @@ atk_relation_set_remove (AtkRelationSet *set,
 
 /**
  * atk_relation_set_add:
- * @set: a #AtkRelationSet
- * @relation: a #AtkRelation
+ * @set: an #AtkRelationSet
+ * @relation: an #AtkRelation
  *
  * Add a new relation to the current relation set if it is not already
  * present.
@@ -163,11 +164,11 @@ atk_relation_set_add (AtkRelationSet *set,
 
 /**
  * atk_relation_set_get_n_relations:
- * @set: a #AtkRelationSet
+ * @set: an #AtkRelationSet
  *
  * Determines the number of relations in a relation set.
  *
- * Returns: a gint representing the number of relations in the set.
+ * Returns: an integer representing the number of relations in the set.
  **/
 gint
 atk_relation_set_get_n_relations (AtkRelationSet *set)
@@ -183,7 +184,7 @@ atk_relation_set_get_n_relations (AtkRelationSet *set)
 
 /**
  * atk_relation_set_get_relation
- * @set: a #AtkRelationSet
+ * @set: an #AtkRelationSet
  * @i: a gint representing a position in the set, starting from 0.
  *
  * Determines the relation at the specified position in the relation set.
@@ -213,12 +214,12 @@ atk_relation_set_get_relation (AtkRelationSet *set,
 
 /**
  * atk_relation_set_get_relation_by_type:
- * @set: a #AtkRelationSet
- * @relationship: a #AtkRelationType
+ * @set: an #AtkRelationSet
+ * @relationship: an #AtkRelationType
  *
  * Finds a relation that matches the specified type.
  *
- * Returns: a #AtkRelation, which is a relation matching the specified type.
+ * Returns: an #AtkRelation, which is a relation matching the specified type.
  **/
 AtkRelation*
 atk_relation_set_get_relation_by_type (AtkRelationSet  *set,
diff --git a/atk/atkselection.c b/atk/atkselection.c
index 2522bb6..54ee722 100755
--- a/atk/atkselection.c
+++ b/atk/atkselection.c
@@ -41,7 +41,7 @@ atk_selection_get_type ()
 
 /**
  * atk_selection_add_selection:
- * @selection: a GObject instance that implements AtkSelectionIface
+ * @selection: a #GObject instance that implements AtkSelectionIface
  * @i: a #gint specifying an accessible child of @selection 
  *
  * Adds the specified accessible child of the object to the
@@ -64,7 +64,7 @@ atk_selection_add_selection (AtkSelection *obj,
 
 /**
  * atk_selection_clear_selection:
- * @selection: a GObject instance that implements AtkSelectionIface
+ * @selection: a #GObject instance that implements AtkSelectionIface
  *
  * Clears the selection in the object so that no children in the object
  * are selected.
@@ -85,18 +85,18 @@ atk_selection_clear_selection (AtkSelection *obj)
 
 /**
  * atk_selection_ref_selection:
- * @selection: a GObject instance that implements AtkSelectionIface
+ * @selection: a #GObject instance that implements AtkSelectionIface
  * @i: a #gint specifying an accessible child of @selection 
  *
  * Gets a reference to the accessible object representing the specified 
- * selected * child of the object.
+ * selected child of the object.
  * Note: callers should not rely on %NULL or on a zero value for
  * indication of whether AtkSelectionIface is implemented, they should
  * use type checking/interface checking macros or the
  * atk_get_accessible_value() convenience method.
  *
- * Returns: a AtkObject* representing the selected accessible , or NULL
- * if value does not implement this interface.
+ * Returns: an #AtkObject representing the selected accessible , or %NULL
+ * if @selection does not implement this interface.
  **/
 AtkObject*
 atk_selection_ref_selection (AtkSelection *obj,
@@ -117,7 +117,7 @@ atk_selection_ref_selection (AtkSelection *obj,
 
 /**
  * atk_selection_get_selection_count:
- * @selection: a GObject instance that implements AtkSelectionIface
+ * @selection: a #GObject instance that implements AtkSelectionIface
  *
  * Gets the number of accessible children currently selected.
  * Note: callers should not rely on %NULL or on a zero value for
@@ -126,7 +126,7 @@ atk_selection_ref_selection (AtkSelection *obj,
  * atk_get_accessible_value() convenience method.
  *
  * Returns: a gint representing the number of items selected, or 0
- * if value does not implement this interface.
+ * if @selection does not implement this interface.
  **/
 gint
 atk_selection_get_selection_count (AtkSelection *obj)
@@ -146,7 +146,7 @@ atk_selection_get_selection_count (AtkSelection *obj)
 
 /**
  * atk_selection_is_child_selected:
- * @selection: a GObject instance that implements AtkSelectionIface
+ * @selection: a #GObject instance that implements AtkSelectionIface
  * @i: a #gint specifying an accessible child of @selection 
  *
  * Determines if the current child of this object is selected
@@ -156,7 +156,7 @@ atk_selection_get_selection_count (AtkSelection *obj)
  * atk_get_accessible_value() convenience method.
  *
  * Returns: a gboolean representing the specified child is selected, or 0
- * if value does not implement this interface.
+ * if @selection does not implement this interface.
  **/
 gboolean
 atk_selection_is_child_selected (AtkSelection *obj,
@@ -177,7 +177,7 @@ atk_selection_is_child_selected (AtkSelection *obj,
 
 /**
  * atk_selection_remove_selection:
- * @selection: a GObject instance that implements AtkSelectionIface
+ * @selection: a #GObject instance that implements AtkSelectionIface
  * @i: a #gint specifying an accessible child of @selection 
  *
  * Removes the specified child of the object from the object's selection.
@@ -199,7 +199,7 @@ atk_selection_remove_selection (AtkSelection *obj,
 
 /**
  * atk_selection_select_all_selection:
- * @selection: a GObject instance that implements AtkSelectionIface
+ * @selection: a #GObject instance that implements AtkSelectionIface
  *
  * Causes every child of the object to be selected if the object
  * supports multiple selections.
diff --git a/atk/atkstate.c b/atk/atkstate.c
index 0e6e4d3..2c0c045 100755
--- a/atk/atkstate.c
+++ b/atk/atkstate.c
@@ -56,7 +56,7 @@ static gchar* state_names[NUM_POSSIBLE_STATES] = {
  * atk_state_type_register:
  * @name: a character string describing the new state.
  *
- * Returns: a #AtkState value for the new state.
+ * Returns: an #AtkState value for the new state.
  **/
 AtkStateType
 atk_state_type_register (const gchar *name)
@@ -95,9 +95,9 @@ atk_state_type_get_name (AtkStateType state)
 
 /**
  * atk_state_type_for_name:
- * @name:
+ * @name: a character string state name
  *
- * Returns:
+ * Returns: an #AtkStateType corresponding to @name 
  */
 AtkStateType
 atk_state_type_for_name (const gchar *name)
diff --git a/atk/atkstateset.c b/atk/atkstateset.c
index 7ff9348..4bcb5de 100755
--- a/atk/atkstateset.c
+++ b/atk/atkstateset.c
@@ -79,11 +79,11 @@ atk_state_set_new (void)
 
 /**
  * atk_state_set_is_empty:
- * @set: a #AtkStateType
+ * @set: an #AtkStateType
  *
  * Checks whether the state set is empty, i.e. has no states set.
  *
- * Returns: %TRUE if @set has no states set
+ * Returns: %TRUE if @set has no states set, otherwise %FALSE
  **/
 gboolean
 atk_state_set_is_empty (AtkStateSet   *set)
@@ -102,8 +102,8 @@ atk_state_set_is_empty (AtkStateSet   *set)
 
 /**
  * atk_state_set_add_state:
- * @set: a #AtkStateSet
- * @type: a #AtkStateType
+ * @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
@@ -130,8 +130,8 @@ atk_state_set_add_state (AtkStateSet   *set,
 }
 /**
  * atk_state_set_add_states:
- * @set: a #AtkStateSet
- * @types: a array of #AtkStateType
+ * @set: an #AtkStateSet
+ * @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
@@ -156,7 +156,7 @@ atk_state_set_add_states (AtkStateSet   *set,
 
 /**
  * atk_state_set_clear_states:
- * @set: a #AtkStateSet
+ * @set: an #AtkStateSet
  *
  * Removes all states from the state set.
  **/
@@ -174,8 +174,8 @@ atk_state_set_clear_states (AtkStateSet   *set)
 
 /**
  * atk_state_set_contains_state:
- * @set: a #AtkStateSet
- * @type: a #AtkStateType
+ * @set: an #AtkStateSet
+ * @type: an #AtkStateType
  *
  * Checks whether the state for the specified type is in the specified set.
  *
@@ -199,8 +199,8 @@ atk_state_set_contains_state (AtkStateSet   *set,
 
 /**
  * atk_state_set_contains_states:
- * @set: a #AtkStateSet
- * @types: a array of #AtkStateType
+ * @set: an #AtkStateSet
+ * @types: an array of #AtkStateType
  * @n_types: The number of elements in the array
  *
  * Checks whether the states for all the specified types are in the 
@@ -230,8 +230,8 @@ atk_state_set_contains_states (AtkStateSet   *set,
 
 /**
  * atk_state_set_remove_state:
- * @set: a #AtkStateSet
- * @type: a #AtkType
+ * @set: an #AtkStateSet
+ * @type: an #AtkType
  *
  * Removes the state for the specified type from the state set.
  *
@@ -258,10 +258,10 @@ atk_state_set_remove_state (AtkStateSet  *set,
 
 /**
  * atk_state_set_and_sets:
- * @set: a #AtkStateSet
+ * @set: an #AtkStateSet
  * @compare_set: another #AtkStateSet
  *
- * Constructs the intersection of the two sets, returning NULL if the
+ * Constructs the intersection of the two sets, returning %NULL if the
  * intersection is empty.
  *
  * Returns: a new #AtkStateSet which is the intersection of the two sets.
@@ -293,7 +293,7 @@ atk_state_set_and_sets (AtkStateSet  *set,
 
 /**
  * atk_state_set_or_sets:
- * @set: a #AtkStateSet
+ * @set: an #AtkStateSet
  * @compare_set: another #AtkStateSet
  *
  * Constructs the union of the two sets.
@@ -326,12 +326,15 @@ atk_state_set_or_sets (AtkStateSet  *set,
 
 /**
  * atk_state_set_xor_sets:
- * @set: a #AtkStateSet
+ * @set: an #AtkStateSet
  * @compare_set: another #AtkStateSet
  *
- * Constructs the xor of the two sets, returing NULL is empty. The set returned by this operation contains the4 sattes in exactly one of the two sets.
+ * Constructs the xor of the two sets, returing %NULL is empty. The set 
+ * returned by this operation contains the4 sattes in exactly one of
+ * the two sets.
  *
- * Returns: a new #AtkStateSet which contains the states which are in exactly one of ht two sets.
+ * Returns: a new #AtkStateSet which contains the states which are 
+ * in exactly one of the two sets.
  **/
 AtkStateSet*
 atk_state_set_xor_sets (AtkStateSet  *set,
diff --git a/atk/atktable.c b/atk/atktable.c
index c2b3149..aab3974 100755
--- a/atk/atktable.c
+++ b/atk/atktable.c
@@ -73,7 +73,7 @@ atk_table_ref_at (AtkTable *obj,
  * @row: a #gint representing a row in @table
  * @column: a #gint representing a column in @table
  *
- * Returns a #gint representing the index at the specified @row and @column,
+ * Gets a #gint representing the index at the specified @row and @column,
  * or 0 if value does not implement this interface.
  * Note: callers should not rely on %NULL or on a zero value for
  * indication of whether AtkSelectionIface is implemented, they should
@@ -106,7 +106,7 @@ atk_table_get_index_at (AtkTable *obj,
  * @table: a GObject instance that implements AtkTableInterface
  * @index: a #gint representing an index in @table
  *
- * Returns a #gint representing the row at the specified @index, or 0
+ * Gets a #gint representing the row at the specified @index, or 0
  * if the value does not implement this interface
  * Note: callers should not rely on %NULL or on a zero value for
  * indication of whether AtkSelectionIface is implemented, they should
@@ -138,7 +138,7 @@ atk_table_get_row_at_index (AtkTable *obj,
  * @table: a GObject instance that implements AtkTableInterface
  * @index: a #gint representing an index in @table
  *
- * Returns a #gint representing the column at the specified @index, or 0
+ * Gets a #gint representing the column at the specified @index, or 0
  * if the value does not implement this interface
  * Note: callers should not rely on %NULL or on a zero value for
  * indication of whether AtkSelectionIface is implemented, they should
diff --git a/atk/atktext.c b/atk/atktext.c
index 8780060..e8471e2 100755
--- a/atk/atktext.c
+++ b/atk/atktext.c
@@ -95,12 +95,12 @@ atk_text_base_init (gpointer *g_class)
 }
 
 /**
- *atk_text_get_text:
- *@text: an #AtkText
- *@start_offset: start position
- *@end_offset: end position
+ * atk_text_get_text:
+ * @text: an #AtkText
+ * @start_offset: start position
+ * @end_offset: end position
  *
- *Returns the text between @start_offset and @end_offset.
+ * Returns: the text from @start_offset up to, but not including @end_offset.
  **/
 gchar*
 atk_text_get_text (AtkText      *text,
@@ -121,11 +121,11 @@ atk_text_get_text (AtkText      *text,
 }
 
 /**
- *atk_text_get_character_at_offset
- *@text: an #AtkText
- *@offset: position
+ * atk_text_get_character_at_offset
+ * @text: an #AtkText
+ * @offset: position
  *
- *Returns the character at @offset.
+ * Returns: the character at @offset.
  **/
 gunichar
 atk_text_get_character_at_offset (AtkText      *text,
@@ -145,12 +145,12 @@ atk_text_get_character_at_offset (AtkText      *text,
 }
 
 /**
- *atk_text_get_text_after_offset
- *@text: an #AtkText
- *@offset: position
- *@boundary_type: An #AtkTextBoundary
+ * atk_text_get_text_after_offset
+ * @text: an #AtkText
+ * @offset: position
+ * @boundary_type: An #AtkTextBoundary
  *
- *Returns the text after @offset up to the specified @boundary_type.
+ * Returns: the text after @offset up to the specified @boundary_type.
  **/
 gchar*
 atk_text_get_text_after_offset (AtkText          *text,
@@ -171,12 +171,12 @@ atk_text_get_text_after_offset (AtkText          *text,
 }
 
 /**
- *atk_text_get_text_at_offset
- *@text: an #AtkText
- *@offset: position
- *@boundary_type: An #AtkTextBoundary
+ * atk_text_get_text_at_offset
+ * @text: an #AtkText
+ * @offset: position
+ * @boundary_type: An #AtkTextBoundary
  *
- *Returns the text at @offset up to the specified @boundary_type.
+ * Returns: the text at @offset up to the specified @boundary_type.
  **/
 gchar*
 atk_text_get_text_at_offset (AtkText          *text,
@@ -197,12 +197,12 @@ atk_text_get_text_at_offset (AtkText          *text,
 }
 
 /**
- *atk_text_get_text_before_offset
- *@text: an #AtkText
- *@offset: position
- *@boundary_type: An #AtkTextBoundary
+ * atk_text_get_text_before_offset
+ * @text: an #AtkText
+ * @offset: position
+ * @boundary_type: An #AtkTextBoundary
  *
- *Returns the text before @offset up to the specified @boundary_type.
+ * Returns: the text before @offset up to the specified @boundary_type.
  **/
 gchar*
 atk_text_get_text_before_offset (AtkText          *text,
@@ -223,10 +223,10 @@ atk_text_get_text_before_offset (AtkText          *text,
 }
 
 /**
- *atk_text_get_caret_offset
- *@text: an #AtkText
+ * atk_text_get_caret_offset
+ * @text: an #AtkText
  *
- *Returns the position of the caret (cursor).
+ * Returns: the position of the caret (cursor).
  **/
 gint
 atk_text_get_caret_offset (AtkText *text)
@@ -245,13 +245,13 @@ atk_text_get_caret_offset (AtkText *text)
 }
 
 /**
- *atk_text_get_row_col_at_offset
- *@text: an #AtkText
- *@offset: position
- *@row: row number
- *@col: column number
+ * atk_text_get_row_col_at_offset
+ * @text: an #AtkText
+ * @offset: position
+ * @row: row number
+ * @col: column number
  *
- *Given an @offset, the @row and @col arguments are filled appropriately.
+ * Given an @offset, the @row and @col arguments are filled appropriately.
  **/
 void
 atk_text_get_row_col_at_offset (AtkText *text,
@@ -276,13 +276,13 @@ atk_text_get_row_col_at_offset (AtkText *text,
 }
 
 /**
- *atk_text_get_range_attributes
- *@text: an #AtkText
- *@start_offset: start position
- *@end_offset: end position
+ * atk_text_get_range_attributes
+ * @text: an #AtkText
+ * @start_offset: start position
+ * @end_offset: end position
  *
- *Returns a #PangoAttrList with the text attributes between the
- *@start_offset and the @end_offset.
+ * Returns a #PangoAttrList with the text attributes between the
+ * @start_offset and the @end_offset.
  **/
 PangoAttrList*
 atk_text_get_range_attributes (AtkText *text,
@@ -303,16 +303,16 @@ atk_text_get_range_attributes (AtkText *text,
 }
 
 /**
- *atk_text_get_character_extents
- *@text: an #AtkText
- *@offset: position
- *@x: x-position of character
- *@y: y-position of character
- *@length: length of character
- *@width: width of character
+ * atk_text_get_character_extents
+ * @text: an #AtkText
+ * @offset: position
+ * @x: x-position of character
+ * @y: y-position of character
+ * @length: length of character
+ * @width: width of character
  *
- *Given an @offset, the @x, @y, @length, and @width values are filled
- *appropriately.
+ * Given an @offset, the @x, @y, @length, and @width values are filled
+ * appropriately.
  **/
 void
 atk_text_get_character_extents (AtkText *text,
@@ -341,10 +341,10 @@ atk_text_get_character_extents (AtkText *text,
 }
 
 /**
- *atk_text_get_character_count
- *@text: an #AtkText
+ * atk_text_get_character_count
+ * @text: an #AtkText
  *
- *Returns the number of characters.
+ * Returns: the number of characters.
  **/
 gint
 atk_text_get_character_count (AtkText *text)
@@ -363,13 +363,13 @@ atk_text_get_character_count (AtkText *text)
 }
 
 /**
- *atk_text_get_offset_at_point
- *@text: an #AtkText
- *@x: x-position of character
- *@y: y-position of character
+ * atk_text_get_offset_at_point
+ * @text: an #AtkText
+ * @x: x-position of character
+ * @y: y-position of character
  *
- *Returns the offset to the character which is located at
- *the specified @x and @y coordinates.
+ * Returns: the offset to the character which is located at
+ * the specified @x and @y coordinates.
  **/
 gint
 atk_text_get_offset_at_point (AtkText *text,
@@ -390,10 +390,10 @@ atk_text_get_offset_at_point (AtkText *text,
 }
 
 /**
- *atk_text_get_selected_text
- *@text: an #AtkText
+ * atk_text_get_selected_text
+ * @text: an #AtkText
  *
- *Returns the selected text.
+ * Returns: the selected text.
  **/
 gchar*
 atk_text_get_selected_text (AtkText *text)
@@ -412,13 +412,13 @@ atk_text_get_selected_text (AtkText *text)
 }
 
 /**
- *atk_text_get_selection_bounds
- *@text: an #AtkText
- *@start_offset: start position
- *@end_offset: end position
+ * atk_text_get_selection_bounds
+ * @text: an #AtkText
+ * @start_offset: start position
+ * @end_offset: end position
  *
- *@start_offset and @end_offset are filled with the
- *current selection bounds.
+ * @start_offset and @end_offset are filled with the
+ * current selection bounds.
  **/
 void
 atk_text_get_selection_bounds (AtkText *text,
@@ -442,14 +442,15 @@ atk_text_get_selection_bounds (AtkText *text,
 }
 
 /**
- *atk_text_set_selection_bounds
- *@text: an #AtkText
- *@start_offset: start position
- *@end_offset: end position
+ * atk_text_set_selection_bounds
+ * @text: an #AtkText
+ * @start_offset: start position
+ * @end_offset: end position
  *
- *The selection bounds are set to the specified @start_offset
- *and @end_offset values.
- *Returns TRUE if success, FALSE otherwise.
+ * The selection bounds are set to the specified @start_offset
+ * and @end_offset values.
+ * 
+ * Returns: %TRUE if success, %FALSE otherwise.
  **/
 gboolean
 atk_text_set_selection_bounds (AtkText *text,
@@ -474,12 +475,13 @@ atk_text_set_selection_bounds (AtkText *text,
 }
 
 /**
- *atk_text_set_caret_offset
- *@text: an #AtkText
- *@offset: position
+ * atk_text_set_caret_offset
+ * @text: an #AtkText
+ * @offset: position
  *
- *Sets the caret (cursor) position to the specified @offset.
- *Returns TRUE if success, FALSE otherwise.
+ * Sets the caret (cursor) position to the specified @offset.
+ *
+ * Returns: %TRUE if success, %FALSE otherwise.
  **/
 gboolean
 atk_text_set_caret_offset (AtkText *text,
diff --git a/atk/atkutil.c b/atk/atkutil.c
index 09e2718..e7c26ac 100755
--- a/atk/atkutil.c
+++ b/atk/atkutil.c
@@ -40,8 +40,8 @@ struct _FocusTracker {
 typedef struct _FocusTracker FocusTracker;
   
 /**
- *atk_focus_tracker_init:
- *@add_function: Function to be called for focus tracker initialization
+ * atk_focus_tracker_init:
+ * @add_function: Function to be called for focus tracker initialization
  *
  * Specifies the function to be called for focus tracker initialization.
  * This function should be called by an implementation of the
@@ -56,8 +56,8 @@ atk_focus_tracker_init (AtkFocusTrackerInit    init)
 }
 
 /**
- *atk_add_focus_tracker:
- *@focus_tracker: Function to be added to the list of functions to be called
+ * atk_add_focus_tracker:
+ * @focus_tracker: Function to be added to the list of functions to be called
  * when an object receives focus. 
  *
  * Adds the specified function to the list of functions to be called
@@ -95,8 +95,8 @@ atk_add_focus_tracker (AtkFocusTracker   focus_tracker)
 }
 
 /**
- *atk_remove_focus_tracker:
- *@tracker_id: the id of the focus tracker to remove
+ * atk_remove_focus_tracker:
+ * @tracker_id: the id of the focus tracker to remove
  *
  * Removes the specified focus tracker from the list of functions
  * to be called when any object receives focus
@@ -126,8 +126,8 @@ atk_remove_focus_tracker (guint            tracker_id)
 }
 
 /**
- *atk_focus_tracker_notify:
- *@object: an #AtkObject
+ * atk_focus_tracker_notify:
+ * @object: an #AtkObject
  *
  * Cause the focus tracker functions which have been specified to be
  * executed for the object.
diff --git a/atk/atkvalue.c b/atk/atkvalue.c
index 3972344..2370037 100755
--- a/atk/atkvalue.c
+++ b/atk/atkvalue.c
@@ -127,7 +127,7 @@ atk_value_get_minimum_value (AtkValue *obj,
  *
  * Sets the value of this object
  *
- * Returns: %true if new value is successfully set, %false otherwise.
+ * Returns: %TRUE if new value is successfully set, %FALSE otherwise.
  **/
 gboolean
 atk_value_set_current_value (AtkValue *obj,