From 3aedda07471e2692ff1361bac6af433b52dec629 Mon Sep 17 00:00:00 2001 From: Bill Haneman Date: Tue, 21 Mar 2006 17:52:39 +0000 Subject: [PATCH] Improved documentation: ATK now has 100% gtk-doc coverage with no sections tagged as incomplete. --- ChangeLog | 20 +++++++++++++++++++ atk/atkdocument.c | 15 ++++++++------ atk/atkimage.c | 8 ++++++-- atk/atkobject.c | 13 +++++++++---- atk/atkobject.h | 18 +++++++++++++++++ atk/atkrelationtype.h | 4 ++-- atk/atktext.h | 18 ++++++++++------- atk/atkutil.h | 21 ++++++++++++++++++++ docs/atk-sections.txt | 7 +++++++ docs/tmpl/atkcomponent.sgml | 9 +++++++++ docs/tmpl/atkdocument.sgml | 39 +++++++++++++++++++++++++++++++++++++ docs/tmpl/atkhypertext.sgml | 8 ++++++-- docs/tmpl/atkimage.sgml | 9 +++++++++ docs/tmpl/atkobject.sgml | 13 +++++++++++-- docs/tmpl/atkregistry.sgml | 6 +++++- docs/tmpl/atkrelationset.sgml | 7 ++++++- docs/tmpl/atkstreamablecontent.sgml | 17 +++++++++++++++- docs/tmpl/atkutil.sgml | 2 +- 18 files changed, 205 insertions(+), 29 deletions(-) diff --git a/ChangeLog b/ChangeLog index 21b33ac..582ad1a 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,23 @@ +2006-03-21 Bill Haneman + + gtk-doc documentation fixes: ATK now has 100% API coverage + with no incomplete function/struct descriptions. + + * atk/atkdocument.c: Edited docs to make gtk-doc happier. + * atk/atkimage.c: Ditto. + * atk/atkobject.c: Moved 'Deprecated' tag relative to 'Returns', + to make gtk-doc happier. + * atk/atkobject.h: Documented AtkPropertyValues. + * atk/atkrelationtypes: Documented the unused/invalid types + ATK_RELATION_TYPE_NULL and ATK_RELATION_TYPE_LAST_DEFINED. + * atk/atktext.h: Documented AtkTextBoundaryType. + * atk/atkutil.h: Documented AtkKeyEventStruct. + * docs/atksections.txt: Added missing function entries. + * docs/tmpl/atkhypertext.sgml: Added long description. + * docs/tmpl/atkregistry.sgml: Added long description. + * docs/tmpl/atkrelationset.sgml: Added long description. + * docs/tmpl/atkstreamablecontent.sgml: Added long description. + 2006-03-21 Tor Lillqvist * atk/atkobject.c (get_atk_locale_dir): Fix fatal typo. diff --git a/atk/atkdocument.c b/atk/atkdocument.c index 429734b..bc49444 100755 --- a/atk/atkdocument.c +++ b/atk/atkdocument.c @@ -136,10 +136,11 @@ atk_document_get_locale (AtkDocument *document) * Gets an AtkAttributeSet which describes document-wide * attributes as name-value pairs. * + * @Since: ATK 1.12 + * * Returns: An AtkAttributeSet containing the explicitly * set name-value-pair attributes associated with this document * as a whole. - * @Since: ATK 1.12 **/ AtkAttributeSet * atk_document_get_attributes (AtkDocument *document) @@ -166,10 +167,11 @@ atk_document_get_attributes (AtkDocument *document) * @attribute_name: a character string representing the name of the attribute * whose value is being queried. * + * @Since: ATK 1.12 + * * Returns: a string value associated with the named attribute for this * document, or NULL if a value for #attribute_name has not been specified * for this document. - * @Since: ATK 1.12 */ G_CONST_RETURN gchar * atk_document_get_attribute_value (AtkDocument *document, @@ -196,17 +198,18 @@ atk_document_get_attribute_value (AtkDocument *document, * @document: a #GObject instance that implements AtkDocumentIface * @attribute_name: a character string representing the name of the attribute * whose value is being set. - * @value: a string value to be associated with #attribute_name. + * @attribute_value: a string value to be associated with #attribute_name. + * + * @Since: ATK 1.12 * * Returns: TRUE if #value is successfully associated with #attribute_name * for this document, FALSE otherwise (e.g. if the document does not * allow the attribute to be modified). - * @Since ATK 1.12 */ gboolean atk_document_set_attribute_value (AtkDocument *document, const gchar *attribute_name, - const gchar *value) + const gchar *attribute_value) { AtkDocumentIface *iface; @@ -216,7 +219,7 @@ atk_document_set_attribute_value (AtkDocument *document, if (iface->set_document_attribute) { - return (iface->set_document_attribute) (document, attribute_name, value); + return (iface->set_document_attribute) (document, attribute_name, attribute_value); } else { diff --git a/atk/atkimage.c b/atk/atkimage.c index 3566d67..30c2705 100755 --- a/atk/atkimage.c +++ b/atk/atkimage.c @@ -187,10 +187,14 @@ 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. +/** + * atk_image_get_image_locale: * @image: An #AtkImage + * * @Since ATK 1.12 + * + * 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. + * */ G_CONST_RETURN gchar* atk_image_get_image_locale (AtkImage *image) diff --git a/atk/atkobject.c b/atk/atkobject.c index bb2c560..d2f88bb 100755 --- a/atk/atkobject.c +++ b/atk/atkobject.c @@ -737,9 +737,9 @@ atk_object_get_role (AtkObject *accessible) * * Gets the layer of the accessible. * - * Returns: an #AtkLayer which is the layer of the accessible - * * @Deprecated: Use atk_component_get_layer instead. + * + * Returns: an #AtkLayer which is the layer of the accessible **/ AtkLayer atk_object_get_layer (AtkObject *accessible) @@ -762,11 +762,12 @@ atk_object_get_layer (AtkObject *accessible) * Gets the zorder of the accessible. The value G_MININT will be returned * if the layer of the accessible is not ATK_LAYER_MDI. * + * @Deprecated: Use atk_component_get_mdi_zorder instead. + * * Returns: a gint which is the zorder of the accessible, i.e. the depth at * which the component is shown in relation to other components in the same * container. * - * @Deprecated: Use atk_component_get_mdi_zorder instead. **/ gint atk_object_get_mdi_zorder (AtkObject *accessible) @@ -1028,13 +1029,17 @@ atk_implementor_ref_accessible (AtkImplementor *implementor) /** * 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. * Not all objects have explicit "name-value pair" #AtkAttributeSet properties. + * * @Since ATK 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. */ AtkAttributeSet * atk_object_get_attributes (AtkObject *accessible) diff --git a/atk/atkobject.h b/atk/atkobject.h index 5a53e08..06379bb 100755 --- a/atk/atkobject.h +++ b/atk/atkobject.h @@ -302,6 +302,24 @@ typedef struct _AtkObjectClass AtkObjectClass; typedef struct _AtkRelationSet AtkRelationSet; typedef struct _AtkStateSet AtkStateSet; +/** + * AtkPropertyValues: + * @property_name: The name of the ATK property which is being presented or which has been changed. + * @old_value: The old property value, NULL; in some contexts this value is undefined (see note below). + * @new_value: The new value of the named property. + * + * @note: For most properties the old_value field of AtkPropertyValues will + * not contain a valid value. + * + * Currently, the only property for which old_value is used is + * accessible-state; for instance if there is a focus state the + * property change handler will be called for the object which lost the focus + * with the old_value containing an AtkState value corresponding to focused + * and the property change handler will be called for the object which + * received the focus with the new_value containing an AtkState value + * corresponding to focused. + * + **/ struct _AtkPropertyValues { const gchar *property_name; diff --git a/atk/atkrelationtype.h b/atk/atkrelationtype.h index f59e4fb..6a019a2 100755 --- a/atk/atkrelationtype.h +++ b/atk/atkrelationtype.h @@ -26,7 +26,7 @@ extern "C" { /** *AtkRelationType: - *@ATK_RELATION_NULL: + *@ATK_RELATION_NULL: Not used, represens "no relationship" or an error condition. *@ATK_RELATION_CONTROLLED_BY: Indicates an object controlled by one or more target objects. *@ATK_RELATION_CONTROLLER_FOR: Indicates an object is an controller for one or more target objects. *@ATK_RELATION_LABEL_FOR: Indicates an object is a label for one or more target objects. @@ -45,7 +45,7 @@ extern "C" { * this object's content is visualy embedded in another object. *@ATK_RELATION_POPUP_FOR: Indicates that an object is a popup for another object. *@ATK_RELATION_PARENT_WINDOW_OF: Indicates that an object is a parent window of another object. - *@ATK_RELATION_LAST_DEFINED: + *@ATK_RELATION_LAST_DEFINED: Not used, this value indicates the end of the enumeration. * *Describes the type of the relation **/ diff --git a/atk/atktext.h b/atk/atktext.h index 31b15cd..191e231 100755 --- a/atk/atktext.h +++ b/atk/atktext.h @@ -112,13 +112,17 @@ typedef struct _AtkTextIface AtkTextIface; /** *AtkTextBoundary: - *@ATK_TEXT_BOUNDARY_CHAR: - *@ATK_TEXT_BOUNDARY_WORD_START: - *@ATK_TEXT_BOUNDARY_WORD_END: - *@ATK_TEXT_BOUNDARY_SENTENCE_START: - *@ATK_TEXT_BOUNDARY_SENTENCE_END: - *@ATK_TEXT_BOUNDARY_LINE_START: - *@ATK_TEXT_BOUNDARY_LINE_END: + *@ATK_TEXT_BOUNDARY_CHAR: Boundary is the boundary between characters + * (including non-printing characters) + *@ATK_TEXT_BOUNDARY_WORD_START: Boundary is the start (i.e. first character) of a word. + *@ATK_TEXT_BOUNDARY_WORD_END: Boundary is the end (i.e. last character) of a word. + *@ATK_TEXT_BOUNDARY_SENTENCE_START: Boundary is the first character in a sentence. + *@ATK_TEXT_BOUNDARY_SENTENCE_END: Boundary is the last (terminal) character in a sentence; + * in languages which use "sentence stop" punctuation such as English, the boundary is thus the + * '.', '?', or similar terminal punctuation character. + *@ATK_TEXT_BOUNDARY_LINE_START: Boundary is the initial character of the content or a + * character immediately following a newline, linefeed, or return character. + *@ATK_TEXT_BOUNDARY_LINE_END: Boundary is the linefeed, or return character. * *Text boundary types used for specifying boundaries for regions of text **/ diff --git a/atk/atkutil.h b/atk/atkutil.h index 1dbfcf3..57e804e 100755 --- a/atk/atkutil.h +++ b/atk/atkutil.h @@ -84,6 +84,27 @@ typedef void (*AtkEventListenerInit) (void); typedef gint (*AtkKeySnoopFunc) (AtkKeyEventStruct *event, gpointer func_data); +/** + * AtkKeyEventStruct: + * @type: An AtkKeyEventType, generally one of ATK_KEY_EVENT_PRESS or ATK_KEY_EVENT_RELEASE + * @state: A bitmask representing the state of the modifier keys immediately after the event takes place. + * The meaning of the bits is currently defined to match the bitmask used by GDK in + * GdkEventType.state, see + * http://developer.gnome.org/doc/API/2.0/gdk/gdk-Event-Structures.html#GdkEventKey + * @keyval: A guint representing a keysym value corresponding to those used by GDK and X11: see + * /usr/X11/include/keysymdef.h. + * @length: The length of member #string. + * @string: A string containing one of the following: either a string approximating the text that would + * result from this keypress, if the key is a control or graphic character, or a symbolic name for this keypress. + * Alphanumeric and printable keys will have the symbolic key name in this string member, for instance "A". "0", + * "semicolon", "aacute". Keypad keys have the prefix "KP". + * @keycode: The raw hardware code that generated the key event. This field is raraly useful. + * @timestamp: A timestamp in milliseconds indicating when the event occurred. + * These timestamps are relative to a starting point which should be considered arbitrary, + * and only used to compare the dispatch times of events to one another. + * + * Encapsulates information about a key event. + **/ struct _AtkKeyEventStruct { gint type; guint state; diff --git a/docs/atk-sections.txt b/docs/atk-sections.txt index 755ca85..cb538b2 100644 --- a/docs/atk-sections.txt +++ b/docs/atk-sections.txt @@ -35,6 +35,7 @@ atk_component_remove_focus_handler atk_component_set_extents atk_component_set_position atk_component_set_size +atk_component_get_alpha AtkComponentIface ATK_COMPONENT @@ -54,6 +55,10 @@ atk_rectangle_get_type AtkDocument atk_document_get_document_type atk_document_get_document +atk_document_get_attribute_value +atk_document_set_attribute_value +atk_document_get_attributes +atk_document_get_locale AtkDocumentIface ATK_DOCUMENT @@ -107,6 +112,7 @@ atk_image_get_image_position atk_image_get_image_description atk_image_set_image_description atk_image_get_image_size +atk_image_get_image_locale AtkImageIface ATK_IMAGE @@ -181,6 +187,7 @@ atk_object_notify_state_change atk_object_initialize atk_object_add_relationship atk_object_remove_relationship +atk_object_get_attributes atk_role_get_name atk_role_get_localized_name atk_role_for_name diff --git a/docs/tmpl/atkcomponent.sgml b/docs/tmpl/atkcomponent.sgml index 2ea4585..661ff00 100644 --- a/docs/tmpl/atkcomponent.sgml +++ b/docs/tmpl/atkcomponent.sgml @@ -185,3 +185,12 @@ a component changes. @Returns: + + + + + +@component: +@Returns: + + diff --git a/docs/tmpl/atkdocument.sgml b/docs/tmpl/atkdocument.sgml index 70aead7..89e66d8 100644 --- a/docs/tmpl/atkdocument.sgml +++ b/docs/tmpl/atkdocument.sgml @@ -45,3 +45,42 @@ The AtkDocument structure does not contain any fields. @Returns: + + + + + +@document: +@attribute_name: +@Returns: + + + + + + + +@document: +@attribute_name: +@attribute_value: +@Returns: + + + + + + + +@document: +@Returns: + + + + + + + +@document: +@Returns: + + diff --git a/docs/tmpl/atkhypertext.sgml b/docs/tmpl/atkhypertext.sgml index 20903a5..de83006 100644 --- a/docs/tmpl/atkhypertext.sgml +++ b/docs/tmpl/atkhypertext.sgml @@ -6,12 +6,16 @@ The ATK interface which provides standard mechanism for manipulating hyperlinks. - +An interface used for objects which implement linking between multiple +resource or content locations, or multiple 'markers' within a single +document. A Hypertext instance is associated with one or more Hyperlinks, +which are associated with particular offsets within the Hypertext's included +content. While this interface is derived from Text, there is no requirement that Hypertext instances have textual content; they may implement Image as well, and Hyperlinks need not have non-zero text offsets. - +AtkHyperlink diff --git a/docs/tmpl/atkimage.sgml b/docs/tmpl/atkimage.sgml index 00757b0..16ad5e0 100644 --- a/docs/tmpl/atkimage.sgml +++ b/docs/tmpl/atkimage.sgml @@ -76,3 +76,12 @@ The AtkImage structure does not contain any fields. @height: + + + + + +@image: +@Returns: + + diff --git a/docs/tmpl/atkobject.sgml b/docs/tmpl/atkobject.sgml index 4a0835a..3133191 100644 --- a/docs/tmpl/atkobject.sgml +++ b/docs/tmpl/atkobject.sgml @@ -317,8 +317,8 @@ to class and interface structures to allow for expansion in the future. -@data: -@Returns: +@data: a gpointer to parameter data. +@Returns: Nothing useful, this is only a dummy prototype. @@ -536,6 +536,15 @@ atk_object_connect_property_change_handler(). @Returns: + + + + + +@accessible: +@Returns: + + diff --git a/docs/tmpl/atkregistry.sgml b/docs/tmpl/atkregistry.sgml index a1de43c..73569c0 100644 --- a/docs/tmpl/atkregistry.sgml +++ b/docs/tmpl/atkregistry.sgml @@ -7,7 +7,11 @@ object for an object of a particular GType. - +The AtkRegistry is normally used to create appropriate ATK "peers" for user +interface components. Application developers usually need only interact with +the AtkRegistry by associating appropriate ATK implementation classes with +GObject classes via the atk_registry_set_factory_type call, passing the +appropriate GType for application custom widget classes. diff --git a/docs/tmpl/atkrelationset.sgml b/docs/tmpl/atkrelationset.sgml index 4b61cc8..8b660fd 100644 --- a/docs/tmpl/atkrelationset.sgml +++ b/docs/tmpl/atkrelationset.sgml @@ -6,7 +6,12 @@ A set of AtkRelations, normally the set of AtkRelations which an AtkObject has. - +The AtkRelationSet held by an object establishes its relationships with +objects beyond the normal "parent/child" hierarchical relationships that all +user interface objects have. AtkRelationSets establish whether objects are +labelled or controlled by other components, share group membership with other +components (for instance within a radio-button group), or share content which +"flows" between them, among other types of possible relationships. diff --git a/docs/tmpl/atkstreamablecontent.sgml b/docs/tmpl/atkstreamablecontent.sgml index 5795f29..8822bb9 100644 --- a/docs/tmpl/atkstreamablecontent.sgml +++ b/docs/tmpl/atkstreamablecontent.sgml @@ -6,7 +6,22 @@ The ATK interface which provides access to streamable content. - +An interface whereby an object allows its backing content to be streamed to +clients. Typical implementors would be images or icons, HTML content, or +multimedia display/rendering widgets. + + +Negotiation of content type is allowed. Clients may examine the backing data +and transform, convert, or parse the content in order to present it in an alternate form to end-users. + + +The AtkStreamableContent interface is particularly useful for saving, +printing, or post-processing entire documents, or for persisting alternate +views of a document. If document content itself is being serialized, +stored, or converted, then use of the AtkStreamableContent interface can help +address performance issues. Unlike most ATK interfaces, +this interface is not strongly tied to the current user-agent view of the +a particular document, but may in some cases give access to the underlying model data. diff --git a/docs/tmpl/atkutil.sgml b/docs/tmpl/atkutil.sgml index 08b2507..ca99b5a 100644 --- a/docs/tmpl/atkutil.sgml +++ b/docs/tmpl/atkutil.sgml @@ -21,7 +21,7 @@ information about the current ATK implementation and toolkit version. - +The AtkUtil struct does not contain any fields. -- 2.7.4