Improved documentation: ATK now has 100% gtk-doc coverage with no

sections tagged as incomplete.

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 <bill.haneman@sun.com>
+
+	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  <tml@novell.com>
 
 	* 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
 <SUBSECTION Standard>
 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
 <SUBSECTION Standard>
 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
 <SUBSECTION Standard>
 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: 
 
 
+<!-- ##### FUNCTION atk_component_get_alpha ##### -->
+<para>
+
+</para>
+
+@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: 
 
 
+<!-- ##### FUNCTION atk_document_get_attribute_value ##### -->
+<para>
+
+</para>
+
+@document: 
+@attribute_name: 
+@Returns: 
+
+
+<!-- ##### FUNCTION atk_document_set_attribute_value ##### -->
+<para>
+
+</para>
+
+@document: 
+@attribute_name: 
+@attribute_value: 
+@Returns: 
+
+
+<!-- ##### FUNCTION atk_document_get_attributes ##### -->
+<para>
+
+</para>
+
+@document: 
+@Returns: 
+
+
+<!-- ##### FUNCTION atk_document_get_locale ##### -->
+<para>
+
+</para>
+
+@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.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+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.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+AtkHyperlink
 </para>
 
 <!-- ##### SECTION Stability_Level ##### -->
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: 
 
 
+<!-- ##### FUNCTION atk_image_get_image_locale ##### -->
+<para>
+
+</para>
+
+@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.
 
 </para>
 
-@data: 
-@Returns: 
+@data: a gpointer to parameter data.
+@Returns: Nothing useful, this is only a dummy prototype.
 
 
 <!-- ##### USER_FUNCTION AtkPropertyChangeHandler ##### -->
@@ -536,6 +536,15 @@ atk_object_connect_property_change_handler().
 @Returns: 
 
 
+<!-- ##### FUNCTION atk_object_get_attributes ##### -->
+<para>
+
+</para>
+
+@accessible: 
+@Returns: 
+
+
 <!-- ##### FUNCTION atk_role_get_name ##### -->
 <para>
 
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.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+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.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
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.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+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.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
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.
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-
+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.
+</para>
+<para>
+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.
+</para>
+<para>
+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.
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
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.
 
 <!-- ##### STRUCT AtkUtil ##### -->
 <para>
-
+The AtkUtil struct does not contain any fields.
 </para>