Add some GtkAccessible documentation

Describe the current thinking about how to provide
3rd party accessible implementations.

1 files changed, 22 insertions, 14 deletions

diff --git a/gtk/gtkaccessible.c b/gtk/gtkaccessible.c
index 25f1c94f54..161ab734ce 100644
--- a/gtk/gtkaccessible.c
+++ b/gtk/gtkaccessible.c
@@ -28,13 +28,20 @@
  * SECTION:gtkaccessible
  * @Short_description: Accessibility support for widgets
  * @Title: GtkAccessible
+ *
+ * The #GtkAccessible class is the base class for accessible
+ * implementations for #GtkWidget subclasses. It is a thin
+ * wrapper around #AtkObject, which adds facilities for associating
+ * a widget with its accessible object.
+ *
+ * An accessible implementation for a third-party widget should
+ * derive from #GtkAccessible and implement the suitable interfaces
+ * from ATK, such as #AtkText or #AtkSelection. To establish
+ * the connection between the widget class and its corresponding
+ * acccessible implementation, override the get_accessible vfunc
+ * in #GtkWidgetClass.
  */
 
-/*
- * GtkAccessiblePriv:
- * @widget: The GtkWidget whose properties and features are exported via this
- *   accessible instance
- */
 struct _GtkAccessiblePrivate
 {
   GtkWidget *widget;
@@ -68,7 +75,7 @@ gtk_accessible_class_init (GtkAccessibleClass *klass)
  * Sets the #GtkWidget corresponding to the #GtkAccessible.
  *
  * Since: 2.22
- **/
+ */
 void
 gtk_accessible_set_widget (GtkAccessible *accessible,
                            GtkWidget     *widget)
@@ -82,14 +89,15 @@ gtk_accessible_set_widget (GtkAccessible *accessible,
  * gtk_accessible_get_widget:
  * @accessible: a #GtkAccessible
  *
- * Gets the #GtkWidget corresponding to the #GtkAccessible. The returned widget
- * does not have a reference added, so you do not need to unref it.
+ * Gets the #GtkWidget corresponding to the #GtkAccessible.
+ * The returned widget does not have a reference added, so
+ * you do not need to unref it.
  *
- * Returns: (transfer none): pointer to the #GtkWidget corresponding to
- *   the #GtkAccessible, or %NULL.
+ * Returns: (transfer none): pointer to the #GtkWidget
+ *     corresponding to the #GtkAccessible, or %NULL.
  *
  * Since: 2.22
- **/
+ */
 GtkWidget*
 gtk_accessible_get_widget (GtkAccessible *accessible)
 {
@@ -99,11 +107,11 @@ gtk_accessible_get_widget (GtkAccessible *accessible)
 }
 
 /**
- * gtk_accessible_connect_widget_destroyed
+ * gtk_accessible_connect_widget_destroyed:
  * @accessible: a #GtkAccessible
  *
- * This function specifies the callback function to be called when the widget
- * corresponding to a GtkAccessible is destroyed.
+ * This function specifies the callback function to be called
+ * when the widget corresponding to a GtkAccessible is destroyed.
  */
 void
 gtk_accessible_connect_widget_destroyed (GtkAccessible *accessible)