Added better gtk-doc comments.
[platform/upstream/atk.git] / atk / atkobject.c
index a247971..bf26479 100755 (executable)
@@ -194,6 +194,11 @@ atk_object_init  (AtkObject        *accessible,
 {
 }
 
+/**
+ *atk_implementor_get_type:
+ *
+ *Returns: a #GType
+ **/
 GType
 atk_implementor_get_type (void)
 {
@@ -215,11 +220,12 @@ atk_implementor_get_type (void)
 }
 
 /**
- * atk_object_get_name
+ * atk_object_get_name:
  * @accessible: a #AtkObject
- * return values: a character string representing the accessible name of the object.
  *
  * Gets the accessible name of the accessible
+ *
+ * Returns: a character string representing the accessible name of the object.
  **/
 G_CONST_RETURN gchar*
 atk_object_get_name (AtkObject *accessible)
@@ -237,11 +243,13 @@ atk_object_get_name (AtkObject *accessible)
 }
 
 /**
- * atk_object_get_description
+ * atk_object_get_description:
  * @accessible: a #AtkObject
- * return values: a character string representing the accessible description of the accessible.
  *
  * Gets the accessible description of the accessible
+ *
+ * Returns: a character string representing the accessible description of the accessible.
+ *
  **/
 G_CONST_RETURN gchar*
 atk_object_get_description (AtkObject *accessible)
@@ -259,11 +267,12 @@ atk_object_get_description (AtkObject *accessible)
 }
 
 /**
- * atk_object_get_parent
+ * atk_object_get_parent:
  * @accessible: a #AtkObject
- * return values: a #AtkObject representing the accessible parent of the accessible.
  *
  * Gets the accessible description of the accessible
+ *
+ * Returns: a #AtkObject representing the accessible parent of the accessible.
  **/
 AtkObject*
 atk_object_get_parent (AtkObject *accessible)
@@ -281,11 +290,12 @@ atk_object_get_parent (AtkObject *accessible)
 }
 
 /**
- * atk_object_get_n_accessible_children
+ * atk_object_get_n_accessible_children:
  * @accessible: a #AtkObject
- * return values: a gint representing the number of accessible children of the accessible.
  *
  * Gets the number of accessible children of the accessible
+ *
+ * Returns: a gint representing the number of accessible children of the accessible.
  **/
 gint
 atk_object_get_n_accessible_children (AtkObject *accessible)
@@ -303,14 +313,15 @@ atk_object_get_n_accessible_children (AtkObject *accessible)
 }
 
 /**
- * atk_object_ref_accessible_child
+ * atk_object_ref_accessible_child:
  * @accessible: a #AtkObject
  * @i: a gint representing the position of the child, starting from 0
- * return values: a #AtkObject representing the specified accessible child of the accessible.
  *
- * Returns a reference to the specified accessible child of the object.
+ * 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.
  **/
 AtkObject*
 atk_object_ref_accessible_child (AtkObject   *accessible,
@@ -329,11 +340,12 @@ atk_object_ref_accessible_child (AtkObject   *accessible,
 }
 
 /**
- * atk_object_ref_accessible_child
+ * atk_object_ref_relation_set:
  * @accessible: a #AtkObject
- * return values: a #AtkRelationSet representing the relation set of the object.
  *
- * Returns a relation to the relation set associated of the accessible.
+ * Gets the RelationSet associated with the object
+ *
+ * Returns: a #AtkRelationSet representing the relation set of the object.
  **/
 AtkRelationSet*
 atk_object_ref_relation_set (AtkObject *accessible)
@@ -351,11 +363,10 @@ atk_object_ref_relation_set (AtkObject *accessible)
 }
 
 /**
- * atk_role_register
+ * atk_role_register:
  * @name: a character string describing the new role.
- * return values: a #AtkRole value for the new role.
  *
- * Returns a #AtkRole value for the new role.
+ * Returns: a #AtkRole value for the new role.
  **/
 AtkRole
 atk_role_register (const gchar *name)
@@ -366,11 +377,12 @@ atk_role_register (const gchar *name)
 }
 
 /**
- * atk_object_get_role
+ * atk_object_get_role:
  * @accessible: a #AtkObject
- * return values: a #AtkRole which is the role of the accessible
  *
  * Gets the role of the accessible
+ *
+ * Returns: a #AtkRole which is the role of the accessible
  **/
 AtkRole
 atk_object_get_role (AtkObject *accessible) {
@@ -387,12 +399,13 @@ atk_object_get_role (AtkObject *accessible) {
 }
 
 /**
- * atk_object_ref_state_set
+ * atk_object_ref_state_set:
  * @accessible: a #AtkObject
- * return values: a reference to a #AtkStateSet which is the state set of the accessible
  *
- * returns a reference to the state set of the accessible; the caller should
+ * 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
  **/
 AtkStateSet*
 atk_object_ref_state_set (AtkObject *accessible) {
@@ -409,12 +422,13 @@ atk_object_ref_state_set (AtkObject *accessible) {
 }
 
 /**
- * atk_object_get_index_in_parent
+ * atk_object_get_index_in_parent:
  * @accessible: a #AtkObject
- * return values: a gint which is the index of the accessible in its parent
  *
  * 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
  **/
 gint
 atk_object_get_index_in_parent (AtkObject *accessible)
@@ -432,9 +446,9 @@ atk_object_get_index_in_parent (AtkObject *accessible)
 }
 
 /**
- * atk_object_set_name
+ * atk_object_set_name:
  * @accessible: a #AtkObject
- * @name : a character string to be set as the accessible name
+ * @name: a character string to be set as the accessible name
  *
  * Sets the accessible name of the accessible
  **/
@@ -457,7 +471,7 @@ atk_object_set_name (AtkObject    *accessible,
 }
 
 /**
- * atk_object_set_description
+ * atk_object_set_description:
  * @accessible: a #AtkObject
  * @description : a character string to be set as the accessible description
  *
@@ -482,7 +496,7 @@ atk_object_set_description (AtkObject   *accessible,
 }
 
 /**
- * atk_object_set_parent
+ * atk_object_set_parent:
  * @accessible: a #AtkObject
  * @parent : a #AtkObject to be set as the accessible parent
  *
@@ -503,7 +517,7 @@ atk_object_set_parent (AtkObject *accessible,
 }
 
 /**
- * atk_object_set_role
+ * atk_object_set_role:
  * @accessible: a #AtkObject
  * @role : a #AtkRole to be set as the role
  *
@@ -524,12 +538,13 @@ atk_object_set_role (AtkObject *accessible,
 }
 
 /**
- * atk_object_connect_property_change_handler
+ * atk_object_connect_property_change_handler:
  * @accessible: a #AtkObject
  * @handler : a #AtkPropertyChangeHandler, a function to be called when a property changes its value
- * return values: a guint which is the handler id used in atk_object_remove_property_change_handler
  *
  * 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
  **/
 guint
 atk_object_connect_property_change_handler (AtkObject *accessible,
@@ -549,7 +564,7 @@ atk_object_connect_property_change_handler (AtkObject *accessible,
 }
 
 /**
- * atk_object_remove_property_change_handler
+ * atk_object_remove_property_change_handler:
  * @accessible: a #AtkObject
  * @handler_id : a guint which identifies the handler to be removed.
  * 
@@ -570,11 +585,15 @@ atk_object_remove_property_change_handler  (AtkObject *accessible,
 }
 
 /**
- * atk_implementor_ref_accessible
- * @object: The GObject instance which should implement #AtkImplementorIface
+ * atk_implementor_ref_accessible:
+ * @implementor: The GObject instance which should implement #AtkImplementorIface
  * if a non-null return value is required.
- * Return 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, if
+ * the object implements #AtkObjectIface
  */
 AtkObject *
 atk_implementor_ref_accessible (AtkImplementor *object)