[atk] doc: improve atkutil documentation

[Alejandro Piñeiro Iglesias <apinheiro src gnome org>]

commit 8e5f9acecdeddfba6bf52dd3eda224ec84fce528
Author: Alejandro Piñeiro <apinheiro igalia com>
Date:   Wed Dec 11 12:33:10 2013 +0100

    doc: improve atkutil documentation

 atk/atkutil.c         |   20 ++++++++++++--------
 atk/atkutil.h         |   20 ++++++++++++++++++++
 docs/atk-sections.txt |    1 +
 3 files changed, 33 insertions(+), 8 deletions(-)
---
diff --git a/atk/atkutil.c b/atk/atkutil.c
index dd505d9..058fc6d 100755
--- a/atk/atkutil.c
+++ b/atk/atkutil.c
@@ -369,10 +369,12 @@ atk_util_real_remove_global_event_listener (guint remove_listener)
  *   ATK:AtkText:text-selection-changed
  *   ATK:AtkText:text-insert:system
  *
- * Toolkit implementor note: Atk provides a default implementation for
- * this virtual method, and that implementation should be enough for
- * most of the cases. You should have a really good reason to
- * reimplement this method.
+ * Toolkit implementor note: ATK provides a default implementation for
+ * this virtual method. ATK implementors are discouraged from
+ * reimplementing this method.
+ *
+ * Toolkit implementor note: this method is not intended to be used by
+ * ATK implementors but by ATK consumers.
  *
  * Returns: added event listener id, or 0 on failure.
  **/
@@ -403,10 +405,12 @@ atk_add_global_event_listener (GSignalEmissionHook listener,
  * @listener_id is the value returned by #atk_add_global_event_listener
  * when you registered that event listener.
  *
- * Toolkit implementor note: Atk provides a default implementation for
- * this virtual method, and that implementation should be enough for
- * most of the cases. You should have a really good reason to
- * reimplement this method.
+ * Toolkit implementor note: ATK provides a default implementation for
+ * this virtual method. ATK implementors are discouraged from
+ * reimplementing this method.
+ *
+ * Toolkit implementor note: this method is not intended to be used by
+ * ATK implementors but by ATK consumers.
  *
  * Removes the specified event listener
  **/
diff --git a/atk/atkutil.h b/atk/atkutil.h
index 420d83e..0b0c402 100755
--- a/atk/atkutil.h
+++ b/atk/atkutil.h
@@ -137,6 +137,26 @@ struct _AtkUtil
   GObject parent;
 };
 
+/**
+ * AtkUtilClass:
+ * @add_global_event_listener: adds the specified function to the list
+ *  of functions to be called when an ATK event occurs. ATK
+ *  implementors are discouraged from reimplementing this method.
+ * @remove_global_event_listener: removes the specified function to
+ *  the list of functions to be called when an ATK event occurs. ATK
+ *  implementors are discouraged from reimplementing this method.
+ * @add_key_event_listener: adds the specified function to the list of
+ *  functions to be called when a key event occurs.
+ * @remove_key_event_listener: remove the specified function to the
+ *  list of functions to be called when a key event occurs.
+ * @get_root: gets the root accessible container for the current
+ *  application.
+ * @get_toolkit_name: gets name string for the GUI toolkit
+ *  implementing ATK for this application.
+ * @get_toolkit_version: gets version string for the GUI toolkit
+ *  implementing ATK for this application.
+ *
+ */
 struct _AtkUtilClass
 {
    GObjectClass parent;
diff --git a/docs/atk-sections.txt b/docs/atk-sections.txt
index e4b9c41..36e9b57 100644
--- a/docs/atk-sections.txt
+++ b/docs/atk-sections.txt
@@ -536,6 +536,7 @@ ATK_STREAMABLE_CONTENT_GET_IFACE
 <FILE>atkutil</FILE>
 <TITLE>AtkUtil</TITLE>
 AtkUtil
+AtkUtilClass
 AtkCoordType
 atk_add_focus_tracker
 atk_remove_focus_tracker