From 41d9865761b1e69498a49e868a9fc48f6f81476a Mon Sep 17 00:00:00 2001 From: Mike Gorse Date: Tue, 25 Jan 2011 14:38:00 -0600 Subject: Bug 640574: gobject-introspection annotation and documentation fixes --- atk/Makefile.am | 2 +- atk/atkcomponent.c | 2 +- atk/atkdocument.c | 4 +-- atk/atkgobjectaccessible.c | 6 +++-- atk/atkhyperlink.c | 3 ++- atk/atkhyperlinkimpl.c | 3 ++- atk/atkhypertext.c | 2 +- atk/atkobject.c | 32 ++++++++++++----------- atk/atkobjectfactory.c | 4 +-- atk/atkregistry.c | 10 ++++---- atk/atkrelation.c | 2 +- atk/atkrelationset.c | 8 +++--- atk/atkselection.c | 4 +-- atk/atkstateset.c | 11 ++++---- atk/atkstreamablecontent.c | 4 +-- atk/atktable.c | 19 +++++++------- atk/atktext.c | 16 ++++++------ atk/atkutil.c | 6 +++-- atk/atkutil.h | 6 ++--- docs/tmpl/atkrelation.sgml | 10 ++++++++ docs/tmpl/atkutil.sgml | 63 ++++++++++++++++++++++++++++++++++++++++++++++ 21 files changed, 152 insertions(+), 65 deletions(-) diff --git a/atk/Makefile.am b/atk/Makefile.am index 5f0d617..5e0339b 100644 --- a/atk/Makefile.am +++ b/atk/Makefile.am @@ -161,7 +161,7 @@ Atk-1.0.gir: libatk-1.0.la Makefile Atk_1_0_gir_INCLUDES = GObject-2.0 Atk_1_0_gir_CFLAGS = $(INCLUDES) Atk_1_0_gir_LIBS = libatk-1.0.la -Atk_1_0_gir_SCANNERFLAGS = --pkg-export atk +Atk_1_0_gir_SCANNERFLAGS = --pkg-export atk --warn-all Atk_1_0_gir_FILES = \ $(addprefix $(srcdir)/, $(introspection_sources)) \ $(introspection_generated_sources) diff --git a/atk/atkcomponent.c b/atk/atkcomponent.c index c1c0404..46e80c8 100755 --- a/atk/atkcomponent.c +++ b/atk/atkcomponent.c @@ -186,7 +186,7 @@ atk_component_contains (AtkComponent *component, * Gets a reference to the accessible child, if one exists, at the * coordinate point specified by @x and @y. * - * Returns: a reference to the accessible child, if one exists + * Returns: (transfer full): a reference to the accessible child, if one exists **/ AtkObject* atk_component_ref_accessible_at_point (AtkComponent *component, diff --git a/atk/atkdocument.c b/atk/atkdocument.c index 0195b26..7072713 100755 --- a/atk/atkdocument.c +++ b/atk/atkdocument.c @@ -120,7 +120,7 @@ atk_document_get_document_type (AtkDocument *document) * up to the caller to check atk_document_get_type to determine * how to cast this pointer. * - * Returns: a %gpointer that points to an instance of the DOM. + * Returns: (transfer none): a %gpointer that points to an instance of the DOM. **/ gpointer atk_document_get_document (AtkDocument *document) @@ -184,7 +184,7 @@ atk_document_get_locale (AtkDocument *document) * * Since: 1.12 * - * Returns: An AtkAttributeSet containing the explicitly + * Returns: (transfer none): An AtkAttributeSet containing the explicitly * set name-value-pair attributes associated with this document * as a whole. **/ diff --git a/atk/atkgobjectaccessible.c b/atk/atkgobjectaccessible.c index ef27bb0..e9ba0f3 100644 --- a/atk/atkgobjectaccessible.c +++ b/atk/atkgobjectaccessible.c @@ -62,7 +62,8 @@ atk_gobject_accessible_get_type (void) * * Gets the accessible object for the specified @obj. * - * Returns: a #AtkObject which is the accessible object for the @obj + * Returns: (transfer none): a #AtkObject which is the accessible object for + * the @obj **/ AtkObject* atk_gobject_accessible_for_object (GObject *obj) @@ -107,7 +108,8 @@ atk_gobject_accessible_for_object (GObject *obj) * * Gets the GObject for which @obj is the accessible object. * - * Returns: a #GObject which is the object for which @obj is the accessible object + * Returns: (transfer none): a #GObject which is the object for which @obj is + * the accessible object **/ GObject * atk_gobject_accessible_get_object (AtkGObjectAccessible *obj) diff --git a/atk/atkhyperlink.c b/atk/atkhyperlink.c index 212493f..3fc902d 100755 --- a/atk/atkhyperlink.c +++ b/atk/atkhyperlink.c @@ -217,7 +217,8 @@ atk_hyperlink_get_uri (AtkHyperlink *link, * * Multiple anchors are primarily used by client-side image maps. * - * Returns: an #AtkObject associated with this hyperlinks i-th anchor + * Returns: (transfer none): an #AtkObject associated with this hyperlinks + * i-th anchor **/ AtkObject* atk_hyperlink_get_object (AtkHyperlink *link, diff --git a/atk/atkhyperlinkimpl.c b/atk/atkhyperlinkimpl.c index 22f47ca..45ee44e 100644 --- a/atk/atkhyperlinkimpl.c +++ b/atk/atkhyperlinkimpl.c @@ -46,7 +46,8 @@ atk_hyperlink_impl_get_type (void) * * Gets the hyperlink associated with this object. * - * Returns an AtkHyperlink object which points to this implementing AtkObject. + * Returns: (transfer full): an AtkHyperlink object which points to this + * implementing AtkObject. * * Since: 1.12 **/ diff --git a/atk/atkhypertext.c b/atk/atkhypertext.c index c9b123a..255834c 100755 --- a/atk/atkhypertext.c +++ b/atk/atkhypertext.c @@ -78,7 +78,7 @@ atk_hypertext_base_init (AtkHypertextIface *class) * Gets the link in this hypertext document at index * @link_index * - * Returns: the link in this hypertext document at + * Returns: (transfer none): the link in this hypertext document at * index @link_index **/ AtkHyperlink* diff --git a/atk/atkobject.c b/atk/atkobject.c index fd23b33..54948b1 100755 --- a/atk/atkobject.c +++ b/atk/atkobject.c @@ -736,7 +736,8 @@ atk_object_get_description (AtkObject *accessible) * * Gets the accessible parent of the accessible. * - * Returns: a #AtkObject representing the accessible parent of the accessible + * Returns: (transfer none): a #AtkObject representing the accessible parent + * of the accessible **/ AtkObject* atk_object_get_parent (AtkObject *accessible) @@ -784,8 +785,8 @@ atk_object_get_n_accessible_children (AtkObject *accessible) * The accessible children are 0-based so the first accessible child is * at index 0, the second at index 1 and so on. * - * Returns: an #AtkObject representing the specified accessible child - * of the accessible. + * Returns: (transfer full): an #AtkObject representing the specified + * accessible child of the accessible. **/ AtkObject* atk_object_ref_accessible_child (AtkObject *accessible, @@ -808,7 +809,8 @@ atk_object_ref_accessible_child (AtkObject *accessible, * * Gets the #AtkRelationSet associated with the object. * - * Returns: an #AtkRelationSet representing the relation set of the object. + * Returns: (transfer full): an #AtkRelationSet representing the relation set + * of the object. **/ AtkRelationSet* atk_object_ref_relation_set (AtkObject *accessible) @@ -923,7 +925,7 @@ atk_object_get_mdi_zorder (AtkObject *accessible) * Gets a reference to the state set of the accessible; the caller must * unreference it when it is no longer needed. * - * Returns: a reference to an #AtkStateSet which is the state + * Returns: (transfer full): a reference to an #AtkStateSet which is the state * set of the accessible **/ AtkStateSet* @@ -990,7 +992,7 @@ atk_object_set_name (AtkObject *accessible, /** * atk_object_set_description: * @accessible: an #AtkObject - * @description : a character string to be set as the accessible description + * @description: a character string to be set as the accessible description * * Sets the accessible description of the accessible. **/ @@ -1014,7 +1016,7 @@ atk_object_set_description (AtkObject *accessible, /** * atk_object_set_parent: * @accessible: an #AtkObject - * @parent : an #AtkObject to be set as the accessible parent + * @parent: an #AtkObject to be set as the accessible parent * * Sets the accessible parent of the accessible. **/ @@ -1037,7 +1039,7 @@ atk_object_set_parent (AtkObject *accessible, /** * atk_object_set_role: * @accessible: an #AtkObject - * @role : an #AtkRole to be set as the role + * @role: an #AtkRole to be set as the role * * Sets the role of the accessible. **/ @@ -1067,7 +1069,7 @@ atk_object_set_role (AtkObject *accessible, /** * atk_object_connect_property_change_handler: * @accessible: an #AtkObject - * @handler : a function to be called when a property changes its value + * @handler: a function to be called when a property changes its value * * Specifies a function to be called when a property changes value. * @@ -1093,7 +1095,7 @@ atk_object_connect_property_change_handler (AtkObject *accessible, /** * atk_object_remove_property_change_handler: * @accessible: an #AtkObject - * @handler_id : a guint which identifies the handler to be removed. + * @handler_id: a guint which identifies the handler to be removed. * * Removes a property change handler. **/ @@ -1114,7 +1116,7 @@ atk_object_remove_property_change_handler (AtkObject *accessible, * atk_object_notify_state_change: * @accessible: an #AtkObject * @state: an #AtkState whose state is changed - * @value : a gboolean which indicates whether the state is being set on or off + * @value: a gboolean which indicates whether the state is being set on or off * * Emits a state-change signal for the specified state. **/ @@ -1141,7 +1143,8 @@ atk_object_notify_state_change (AtkObject *accessible, * Gets a reference to an object's #AtkObject implementation, if * the object implements #AtkObjectIface * - * Returns: a reference to an object's #AtkObject implementation + * Returns: (transfer full): a reference to an object's #AtkObject + * implementation */ AtkObject * atk_implementor_ref_accessible (AtkImplementor *implementor) @@ -1173,8 +1176,9 @@ atk_implementor_ref_accessible (AtkImplementor *implementor) * * Since: 1.12 * - * Returns: an #AtkAttributeSet consisting of all explicit properties/annotations applied to - * the object, or an empty set if the object has no name-value pair attributes assigned to it. + * Returns: (transfer none): an #AtkAttributeSet consisting of all explicit + * properties/annotations applied to the object, or an empty set if the object + * has no name-value pair attributes assigned to it. */ AtkAttributeSet * atk_object_get_attributes (AtkObject *accessible) diff --git a/atk/atkobjectfactory.c b/atk/atkobjectfactory.c index 81ab3b3..cef6692 100755 --- a/atk/atkobjectfactory.c +++ b/atk/atkobjectfactory.c @@ -65,8 +65,8 @@ atk_object_factory_class_init (AtkObjectFactoryClass *klass) * Provides an #AtkObject that implements an accessibility interface * on behalf of @obj * - * Returns: an #AtkObject that implements an accessibility interface - * on behalf of @obj + * Returns: (transfer full): an #AtkObject that implements an accessibility + * interface on behalf of @obj **/ AtkObject* atk_object_factory_create_accessible (AtkObjectFactory *factory, diff --git a/atk/atkregistry.c b/atk/atkregistry.c index 1fbf443..fb732c9 100644 --- a/atk/atkregistry.c +++ b/atk/atkregistry.c @@ -206,8 +206,8 @@ atk_registry_get_factory_type (AtkRegistry *registry, * Gets an #AtkObjectFactory appropriate for creating #AtkObjects * appropriate for @type. * - * Returns: an #AtkObjectFactory appropriate for creating #AtkObjects - * appropriate for @type. + * Returns: (transfer none): an #AtkObjectFactory appropriate for creating + * #AtkObjects appropriate for @type. **/ AtkObjectFactory* atk_registry_get_factory (AtkRegistry *registry, @@ -247,7 +247,7 @@ atk_registry_get_factory (AtkRegistry *registry, } /** - *atk_get_default_registry: + * atk_get_default_registry: * * Gets a default implementation of the #AtkObjectFactory/type * registry. @@ -257,8 +257,8 @@ atk_registry_get_factory (AtkRegistry *registry, * to associate an #AtkObjectFactory subclass with the GType of objects * for whom accessibility information will be provided. * - * Returns: a default implementation of the #AtkObjectFactory/type - * registry + * Returns: (transfer full): a default implementation of the + * #AtkObjectFactory/type registry **/ AtkRegistry* atk_get_default_registry (void) diff --git a/atk/atkrelation.c b/atk/atkrelation.c index e4ae7c5..9c26660 100755 --- a/atk/atkrelation.c +++ b/atk/atkrelation.c @@ -282,7 +282,7 @@ atk_relation_get_relation_type (AtkRelation *relation) * * Gets the target list of @relation * - * Returns: the target list of @relation + * Returns: (transfer none): the target list of @relation **/ GPtrArray* atk_relation_get_target (AtkRelation *relation) diff --git a/atk/atkrelationset.c b/atk/atkrelationset.c index da0af10..de52320 100755 --- a/atk/atkrelationset.c +++ b/atk/atkrelationset.c @@ -216,13 +216,14 @@ atk_relation_set_get_n_relations (AtkRelationSet *set) } /** - * atk_relation_set_get_relation + * atk_relation_set_get_relation: * @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. * - * Returns: a #AtkRelation, which is the relation at position i in the set. + * Returns: (transfer none): a #AtkRelation, which is the relation at + * position i in the set. **/ AtkRelation* atk_relation_set_get_relation (AtkRelationSet *set, @@ -251,7 +252,8 @@ atk_relation_set_get_relation (AtkRelationSet *set, * * Finds a relation that matches the specified type. * - * Returns: an #AtkRelation, which is a relation matching the specified type. + * Returns: (transfer none): 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 4088fa8..6209aeb 100755 --- a/atk/atkselection.c +++ b/atk/atkselection.c @@ -132,8 +132,8 @@ atk_selection_clear_selection (AtkSelection *obj) * use type checking/interface checking macros or the * atk_get_accessible_value() convenience method. * - * Returns: an #AtkObject representing the selected accessible , or %NULL - * if @selection does not implement this interface. + * Returns: (transfer full): an #AtkObject representing the selected + * accessible , or %NULL if @selection does not implement this interface. **/ AtkObject* atk_selection_ref_selection (AtkSelection *obj, diff --git a/atk/atkstateset.c b/atk/atkstateset.c index b7654b0..eabb9f9 100755 --- a/atk/atkstateset.c +++ b/atk/atkstateset.c @@ -257,7 +257,8 @@ atk_state_set_remove_state (AtkStateSet *set, * 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. + * Returns: (transfer full): a new #AtkStateSet which is the intersection of + * the two sets. **/ AtkStateSet* atk_state_set_and_sets (AtkStateSet *set, @@ -289,8 +290,8 @@ atk_state_set_and_sets (AtkStateSet *set, * * Constructs the union of the two sets. * - * Returns: a new #AtkStateSet which is the union of the two sets, - * returning %NULL is empty. + * Returns: (transfer full): a new #AtkStateSet which is the union of the two + * sets, returning %NULL is empty. **/ AtkStateSet* atk_state_set_or_sets (AtkStateSet *set, @@ -326,8 +327,8 @@ atk_state_set_or_sets (AtkStateSet *set, * The set returned by this operation contains the states in exactly * one of the two sets. * - * Returns: a new #AtkStateSet which contains the states which are - * in exactly one of the two sets. + * Returns: (transfer full): 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/atkstreamablecontent.c b/atk/atkstreamablecontent.c index d9ea07f..4ef168e 100755 --- a/atk/atkstreamablecontent.c +++ b/atk/atkstreamablecontent.c @@ -97,8 +97,8 @@ atk_streamable_content_get_mime_type (AtkStreamableContent *streamable, * * Gets the content in the specified mime type. * - * Returns: A #GIOChannel which contains the content in the specified mime - * type. + * Returns: (transfer full): A #GIOChannel which contains the content in the + * specified mime type. **/ GIOChannel* atk_streamable_content_get_stream (AtkStreamableContent *streamable, diff --git a/atk/atktable.c b/atk/atktable.c index 5cecaf6..729f6ec 100755 --- a/atk/atktable.c +++ b/atk/atktable.c @@ -138,7 +138,8 @@ atk_table_base_init (gpointer *g_class) * * Get a reference to the table cell at @row, @column. * - * Returns: a AtkObject* representing the referred to accessible + * Returns: (transfer full): a AtkObject* representing the referred to + * accessible **/ AtkObject* atk_table_ref_at (AtkTable *table, @@ -248,8 +249,8 @@ atk_table_get_column_at_index (AtkTable *table, * * Gets the caption for the @table. * - * Returns: a AtkObject* representing the table caption, or %NULL - * if value does not implement this interface. + * Returns: (transfer none): a AtkObject* representing the table caption, or + * %NULL if value does not implement this interface. **/ AtkObject* atk_table_get_caption (AtkTable *table) @@ -352,8 +353,8 @@ atk_table_get_column_extent_at (AtkTable *table, * * Gets the column header of a specified column in an accessible table. * - * Returns: a AtkObject* representing the specified column header, or - * %NULL if value does not implement this interface. + * Returns: (transfer none): a AtkObject* representing the specified column + * header, or %NULL if value does not implement this interface. **/ AtkObject* atk_table_get_column_header (AtkTable *table, gint column) @@ -456,8 +457,8 @@ atk_table_get_row_extent_at (AtkTable *table, * * Gets the row header of a specified row in an accessible table. * - * Returns: a AtkObject* representing the specified row header, or - * %NULL if value does not implement this interface. + * Returns: (transfer none): a AtkObject* representing the specified row + * header, or %NULL if value does not implement this interface. **/ AtkObject* atk_table_get_row_header (AtkTable *table, gint row) @@ -480,8 +481,8 @@ atk_table_get_row_header (AtkTable *table, gint row) * * Gets the summary description of the table. * - * Returns: a AtkObject* representing a summary description of the table, - * or zero if value does not implement this interface. + * Returns: (transfer full): a AtkObject* representing a summary description + * of the table, or zero if value does not implement this interface. **/ AtkObject* atk_table_get_summary (AtkTable *table) diff --git a/atk/atktext.c b/atk/atktext.c index 23cf800..ee3abde 100755 --- a/atk/atktext.c +++ b/atk/atktext.c @@ -599,7 +599,7 @@ atk_text_get_character_extents (AtkText *text, } /** - *atk_text_get_run_attributes: + * atk_text_get_run_attributes: *@text: an #AtkText *@offset: the offset at which to get the attributes, -1 means the offset of *the character to be inserted at the caret location. @@ -614,9 +614,9 @@ atk_text_get_character_extents (AtkText *text, *attributes that can be returned. Note that other attributes may also be *returned. * - *Returns: an #AtkAttributeSet which contains the attributes explicitly set - *at @offset. This #AtkAttributeSet should be freed by a call to - *atk_attribute_set_free(). + *Returns: (transfer full): an #AtkAttributeSet which contains the attributes + * explicitly set at @offset. This #AtkAttributeSet should be freed by a call + * to atk_attribute_set_free(). **/ AtkAttributeSet* atk_text_get_run_attributes (AtkText *text, @@ -651,7 +651,7 @@ atk_text_get_run_attributes (AtkText *text, } /** - *atk_text_get_default_attributes: + * atk_text_get_default_attributes: *@text: an #AtkText * *Creates an #AtkAttributeSet which consists of the default values of @@ -659,9 +659,9 @@ atk_text_get_run_attributes (AtkText *text, *attributes that can be returned. Note that other attributes may also be *returned. * - *Returns: an #AtkAttributeSet which contains the default values of attributes. - *at @offset. This #AtkAttributeSet should be freed by a call to - *atk_attribute_set_free(). + *Returns: (transfer full): an #AtkAttributeSet which contains the default + * values of attributes. at @offset. this #atkattributeset should be freed by + * a call to atk_attribute_set_free(). */ AtkAttributeSet* atk_text_get_default_attributes (AtkText *text) diff --git a/atk/atkutil.c b/atk/atkutil.c index 7de154d..bd4e67a 100755 --- a/atk/atkutil.c +++ b/atk/atkutil.c @@ -298,7 +298,8 @@ atk_remove_key_event_listener (guint listener_id) * * Gets the root accessible container for the current application. * - * Returns: the root accessible container for the current application + * Returns: (transfer none): the root accessible container for the current + * application **/ AtkObject* atk_get_root (void) @@ -325,7 +326,8 @@ atk_get_root (void) * * Since: 1.6 * - * Returns: the currently focused object for the current application + * Returns: (transfer none): the currently focused object for the current + * application **/ AtkObject* atk_get_focus_object (void) diff --git a/atk/atkutil.h b/atk/atkutil.h index 1bf2b6b..b04b1c7 100755 --- a/atk/atkutil.h +++ b/atk/atkutil.h @@ -54,7 +54,7 @@ typedef struct _AtkKeyEventStruct AtkKeyEventStruct; * 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. + * see atk_add_focus_tracker. **/ typedef void (*AtkEventListener) (AtkObject* obj); /** @@ -64,7 +64,7 @@ typedef void (*AtkEventListener) (AtkObject* obj); * called in order to initialize the per-object event registration system * used by #AtkEventListener, if any preparation is required. * - * @see: atk_focus_tracker_init. + * see atk_focus_tracker_init. **/ typedef void (*AtkEventListenerInit) (void); /** @@ -81,7 +81,7 @@ typedef void (*AtkEventListenerInit) (void); * 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. + * see atk_add_key_event_listener. **/ typedef gint (*AtkKeySnoopFunc) (AtkKeyEventStruct *event, gpointer func_data); diff --git a/docs/tmpl/atkrelation.sgml b/docs/tmpl/atkrelation.sgml index 477f272..d83f1e8 100644 --- a/docs/tmpl/atkrelation.sgml +++ b/docs/tmpl/atkrelation.sgml @@ -131,3 +131,13 @@ The AtkRelation structure should not be accessed directly. @target: + + + + + +@relation: +@target: +@Returns: + + diff --git a/docs/tmpl/atkutil.sgml b/docs/tmpl/atkutil.sgml index 50e7fbd..6331d36 100644 --- a/docs/tmpl/atkutil.sgml +++ b/docs/tmpl/atkutil.sgml @@ -189,3 +189,66 @@ The AtkUtil struct does not contain any fields. @Returns: + + + + + +@void: +@Returns: + + + + + + + +@TN: +@t_n: +@T_P: + + + + + + + +@TN: +@t_n: +@T_P: +@_f_: +@_C_: + + + + + + + +@TN: +@t_n: +@T_P: +@_C_: + + + + + + + +@TN: +@t_n: +@T_P: + + + + + + + +@TN: +@t_n: +@T_P: +@_C_: + + -- cgit v1.2.1