Merge lp:~bregma/libgrip/lp-744911 into lp:libgrip

[Stephen M. Webb]

Adds gtk-doc reference docs.

Once packaged, this should satisfy bug lp:744911.

[Chase Douglas (chasedouglas)]

I don't know exactly how the docs turn out, but I trust Stephen on making documentation :).

[Stephen M. Webb (bregma)]

An example of the generated docs can now be found here: <http://people.canonical.com/~stephenwebb/libgrip/>

[Duncan McGreggor (oubiwann)]

Thanks for the docs (and the link) Stephen!

So I have one comment, and you're free to go either route. But first, here's a list of the components that seem to be missing documentation:
 * struct GripGestureManagerClass
 * union GripGestureEvent
 * struct GripEventGestureAny
 * grip_gesture_event_new ()
 * grip_gesture_event_free ()
 * grip_gesture_event_copy ()

We should do one of the following:

 1) add docs (even a short one-sentence description) for the 6 listed above, or
 2) be prepared to update the docs when asked by community members.

I'd prefer option #1, but if it's a matter of being unclear of the exact usage, and there being too much overhead in tracking down the folks that know, we can do #2.

However, if we go that route, it means that we need to be *very* conscientious: as soon as we answer a question in-channel (or mail list) or find an answer out from someone who knows, we need to file a ticket to update the docs, and add that information immediately.

I will set my review to "approve" -- however, don't merge yet. Let's get a review from David Planella.

review: Approve

[lp:~bregma/libgrip/lp-744911]

42. By Stephen M. Webb on 2011-04-13

More final documentation tweaks, for the remaining undocumented bits.

=== added file '.bzrignore'
--- .bzrignore	1970-01-01 00:00:00 +0000
+++ .bzrignore	2011-04-13 18:27:31 +0000
@@ -0,0 +1,26 @@
+*.gir
+*.la
+*.lo
+*.make
+*.pc
+*.stamp
+*.typelib
+.deps
+.libs
+aclocal.m4
+autom4te.cache
+config.*
+depcomp
+doc/reference/*.sgml
+doc/reference/*.txt
+doc/reference/html
+doc/reference/tmpl
+doc/reference/xml
+examples/rectangle-mover/grip-test
+libtool
+ltmain.sh
+Makefile
+Makefile.in
+missing
+src/griptypebuiltins.*
+stamp-*

=== modified file 'Makefile.am'
--- Makefile.am	2011-03-09 03:00:31 +0000
+++ Makefile.am	2011-04-13 18:27:31 +0000
@@ -1,4 +1,4 @@
-SUBDIRS = src bindings examples/rectangle-mover
+SUBDIRS = src bindings examples/rectangle-mover doc
 
 libgrip-0.1.pc: libgrip.pc
 	cp -f libgrip.pc libgrip-0.1.pc
@@ -12,7 +12,7 @@
 
 ACLOCAL_AMFLAGS=-I m4
 
-DISTCHECK_CONFIGURE_FLAGS = --disable-gtk-doc
+DISTCHECK_CONFIGURE_FLAGS = --enable-gtk-doc --enable-introspection --enable-localinstall
 
 dist-hook:
 	@if test -d "$(top_srcdir)/.bzr";								\

=== modified file 'configure.ac'
--- configure.ac	2011-03-23 18:13:02 +0000
+++ configure.ac	2011-04-13 18:27:31 +0000
@@ -119,6 +119,9 @@
   bindings/Makefile
   examples/rectangle-mover/Makefile
   libgrip.pc
+  doc/Makefile
+  doc/reference/Makefile
+  doc/reference/libgrip-docs.sgml
 ])
 
 AC_OUTPUT

=== added directory 'doc'
=== added file 'doc/Makefile.am'
--- doc/Makefile.am	1970-01-01 00:00:00 +0000
+++ doc/Makefile.am	2011-04-13 18:27:31 +0000
@@ -0,0 +1,2 @@
+SUBDIRS = reference
+

=== added directory 'doc/reference'
=== added file 'doc/reference/Makefile.am'
--- doc/reference/Makefile.am	1970-01-01 00:00:00 +0000
+++ doc/reference/Makefile.am	2011-04-13 18:27:31 +0000
@@ -0,0 +1,106 @@
+## Process this file with automake to produce Makefile.in
+
+# This is a blank Makefile.am for using gtk-doc.
+# Copy this to your project's API docs directory and modify the variables to
+# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples
+# of using the various options.
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE=libgrip
+
+# Uncomment for versioned docs and specify the version of the module, e.g. '2'.
+#DOC_MODULE_VERSION=2
+
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
+
+# Directories containing the source code, relative to $(srcdir).
+# gtk-doc will search all .c and .h files beneath these paths
+# for inline comments documenting functions and macros.
+# e.g. DOC_SOURCE_DIR=../../../gtk ../../../gdk
+DOC_SOURCE_DIR=$(top_srcdir)/src
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS=
+
+# Extra options to supply to gtkdoc-scan.
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
+SCAN_OPTIONS=
+
+# Extra options to supply to gtkdoc-mkdb.
+# e.g. MKDB_OPTIONS=--xml-mode --output-format=xml
+MKDB_OPTIONS=--xml-mode --output-format=xml
+
+# Extra options to supply to gtkdoc-mktmpl
+# e.g. MKTMPL_OPTIONS=--only-section-tmpl
+MKTMPL_OPTIONS=
+
+# Extra options to supply to gtkdoc-mkhtml
+MKHTML_OPTIONS=
+
+# Extra options to supply to gtkdoc-fixref. Not normally needed.
+# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
+FIXXREF_OPTIONS=
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
+# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
+HFILE_GLOB=$(DOC_SOURCE_DIR)/*.h
+CFILE_GLOB=$(DOC_SOURCE_DIR)/*.c
+
+# Extra header to include when scanning, which are not under DOC_SOURCE_DIR
+# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h
+EXTRA_HFILES=
+
+# Header files or dirs to ignore when scanning. Use base file/dir names
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code
+IGNORE_HFILES=
+
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+HTML_IMAGES=
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
+content_files=
+
+# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# These files must be listed here *and* in content_files
+# e.g. expand_content_files=running.sgml
+expand_content_files=
+
+# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
+# Only needed if you are using gtkdoc-scangobj to dynamically query widget
+# signals and properties.
+# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+GTKDOC_CFLAGS=$(GTK_CFLAGS)
+GTKDOC_LIBS=$(top_builddir)/src/libgrip-0.1.la $(GTK_LIBS)
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+# Other files to distribute
+# e.g. EXTRA_DIST += version.xml.in
+EXTRA_DIST += libgrip-docs.sgml.in
+
+# Files not to distribute
+# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
+# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt
+#DISTCLEANFILES +=
+
+# Comment this out if you want 'make check' to test you doc status
+# and run some sanity checks
+if ENABLE_GTK_DOC
+TESTS_ENVIRONMENT = cd $(srcdir) && \
+  DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \
+  SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir)
+#TESTS = $(GTKDOC_CHECK)
+endif
+
+dist-hook-local: gtk-docs-clean all-local
+
+gtk-docs-clean: clean
+	rm -rf xml tmpl html
+

=== added file 'doc/reference/libgrip-docs.sgml.in'
--- doc/reference/libgrip-docs.sgml.in	1970-01-01 00:00:00 +0000
+++ doc/reference/libgrip-docs.sgml.in	2011-04-13 18:27:31 +0000
@@ -0,0 +1,51 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+]>
+<book id="index">
+  <bookinfo>
+    <title>libgrip Reference Manual</title>
+    <releaseinfo>
+      for @PACKAGE@ @VERSION@.
+    </releaseinfo>
+  </bookinfo>
+
+  <chapter id="libgrip">
+    <title>libgrip Overview</title>
+    <para>
+      The libgrip library provides multi-touch and gesture events to GTK widgets.
+    </para>
+
+    <para>
+      The libgrip library provides a singleton GripGestureManager that maintains
+      a connection to the gesture recognizer.  Any widgets interested in acting
+      on gestures must register one or more callback functions with the
+      GripGestureManager, one per gesture primitive.  The widgets will receive
+      data describing the ongoing state of gestures as they occur, and must take
+      appropriate action in the callback function.
+    </para>
+  </chapter>
+
+  <chapter id="libgrip-api">
+    <title>Programming Interface</title>
+    <xi:include href="xml/GripGestureManager.xml"/>
+    <xi:include href="xml/GripGestureEvents.xml"/>
+  </chapter>
+
+  <chapter id="object-tree">
+    <title>Object Hierarchy</title>
+     <xi:include href="xml/tree_index.sgml"/>
+  </chapter>
+  <index id="api-index-full">
+    <title>API Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="deprecated-api-index" role="deprecated">
+    <title>Index of deprecated API</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+</book>

=== added file 'doc/reference/libgrip-sections.txt'
--- doc/reference/libgrip-sections.txt	1970-01-01 00:00:00 +0000
+++ doc/reference/libgrip-sections.txt	2011-04-13 18:27:31 +0000
@@ -0,0 +1,53 @@
+<SECTION>
+<FILE>GripGestureManager</FILE>
+<TITLE>GripGestureManager</TITLE>
+GripGestureManager
+GripGestureManagerClass
+
+grip_gesture_manager_get
+
+<SUBSECTION>
+GripGestureCallback
+
+grip_gesture_manager_register_window
+
+<SUBSECTION Standard>
+GRIP_TYPE_GESTURE_MANAGER
+GRIP_GESTURE_MANAGER
+GRIP_IS_GESTURE_MANAGER
+GRIP_GESTURE_MANAGER_CLASS
+GRIP_IS_GESTURE_MANAGER_CLASS
+GRIP_GESTURE_MANAGER_GET_CLASS
+
+<SUBSECTION Private>
+GripGestureManagerPrivate
+grip_gesture_manager_get_type
+</SECTION>
+
+
+<SECTION>
+<FILE>GripGestureEvents</FILE>
+<TITLE>Gesture Events</TITLE>
+GripGestureType
+
+<SUBSECTION>
+GripTimeType
+
+<SUBSECTION>
+GripGestureEvent
+GripEventGestureAny
+GripEventGestureDrag
+GripEventGesturePinch
+GripEventGestureRotate
+GripEventGestureTap
+grip_gesture_event_new
+grip_gesture_event_free
+grip_gesture_event_copy
+<SUBSECTION Private>
+GRIP_TYPE_GESTURE_TYPE
+grip_gesture_type_get_type
+grip_gesture_event_get_type
+GRIP_TYPE_TIME_TYPE
+grip_time_type_get_type
+</SECTION>
+

=== added file 'doc/reference/libgrip.types'
--- doc/reference/libgrip.types	1970-01-01 00:00:00 +0000
+++ doc/reference/libgrip.types	2011-04-13 18:27:31 +0000
@@ -0,0 +1,4 @@
+grip_gesture_event_get_type
+grip_gesture_manager_get_type
+grip_gesture_type_get_type
+grip_time_type_get_type

=== modified file 'src/gripgesturemanager.c'
--- src/gripgesturemanager.c	2011-03-23 15:17:02 +0000
+++ src/gripgesturemanager.c	2011-04-13 18:27:31 +0000
@@ -1,5 +1,5 @@
 /*
- * Copyright 2010 Canonical, Ltd.
+ * Copyright 2010, 2011 Canonical, Ltd.
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of either or both of the following licenses:
@@ -1165,7 +1165,7 @@
 /**
  * grip_gesture_manager_register_window:
  * @manager: A #GripGestureManager instance.
- * @window: A #GtkWindow to register the gesture event for.
+ * @widget: A #GtkWidget to register the gesture event for.
  * @gesture_type: The type of gesture event to register.
  * @touch_points: Number of touch points for this gesture.
  * @callback: Called when a gesture starts, updates, or ends.
@@ -1260,16 +1260,33 @@
   return type;
 }
 
+/**
+ * grip_gesture_event_new:
+ * @gesture_type: the type of the gesture
+ *
+ * Creates a new Grip gesture event.
+ *
+ * Returns: a new #GripGestureEvent
+ */
 GripGestureEvent *
-grip_gesture_event_new (GripGestureType type)
+grip_gesture_event_new (GripGestureType gesture_type)
 {
   GripGestureEvent *event = g_slice_new0 (GripGestureEvent);
 
-  event->any.type = type;
+  event->any.type = gesture_type;
 
   return event;
 }
 
+/**
+ * grip_gesture_event_copy:
+ * @event: an existing #GripGestureEvent
+ *
+ * Creates a new #GripGestureEvent instance using a deep copy of and existing
+ * event.
+ *
+ * Returns: a new #GripGestureEvent
+ */
 GripGestureEvent *
 grip_gesture_event_copy (const GripGestureEvent *event)
 {
@@ -1283,6 +1300,12 @@
   return new_event;
 }
 
+/**
+ * grip_gesture_event_free:
+ * @event: a #GripGestureEvent
+ *
+ * Frees the resources allocated for a #GripGestureEvent.
+ */
 void
 grip_gesture_event_free (GripGestureEvent *event)
 {

=== modified file 'src/gripgesturemanager.h'
--- src/gripgesturemanager.h	2011-03-23 15:17:02 +0000
+++ src/gripgesturemanager.h	2011-04-13 18:27:31 +0000
@@ -1,5 +1,5 @@
 /*
- * Copyright 2010 Canonical, Ltd.
+ * Copyright 2010, 2011 Canonical, Ltd.
  *
  * This program is free software: you can redistribute it and/or modify it
  * under the terms of either or both of the following licenses:
@@ -30,12 +30,70 @@
 
 G_BEGIN_DECLS
 
-#define GRIP_TYPE_GESTURE_MANAGER         (grip_gesture_manager_get_type ())
-#define GRIP_GESTURE_MANAGER(o)           (G_TYPE_CHECK_INSTANCE_CAST ((o), GRIP_TYPE_GESTURE_MANAGER, GripGestureManager))
-#define GRIP_GESTURE_MANAGER_CLASS(c)     (G_TYPE_CHECK_CLASS_CAST ((c), GRIP_TYPE_GESTURE_MANAGER, GripGestureManagerClass))
-#define GRIP_IS_GESTURE_MANAGER(o)        (G_TYPE_CHECK_INSTANCE_TYPE ((o), GRIP_TYPE_GESTURE_MANAGER))
-#define GRIP_IS_GESTURE_MANAGER_CLASS(c)  (G_TYPE_CHECK_CLASS_TYPE ((c), GRIP_TYPE_GESTURE_MANAGER))
-#define GRIP_GESTURE_MANAGER_GET_CLASS(o) (G_TYPE_INSTANCE_GET_CLASS ((o), GRIP_TYPE_GESTURE_MANAGER, GripGestureManagerClass))
+/**
+ * SECTION:GripGestureManager
+ *
+ * The Grip gesture managre is a singleton object that connections to the
+ * gesture recognition engine and manages gesture subscriptions for GTK widgets.
+ */
+
+/**
+ * SECTION:GripGestureEvents
+ *
+ * A series of one or more events are passed to the gesture callback.  Each
+ * event conveys information specific to the type of gesture occurring.
+ */
+
+/**
+ * GRIP_TYPE_GESTURE_MANAGER:
+ *
+ * Gets the #GType for the #GripGestureManager.
+ */
+#define GRIP_TYPE_GESTURE_MANAGER            (grip_gesture_manager_get_type ())
+
+/**
+ * GRIP_GESTURE_MANAGER:
+ * @obj: The #GObject to convert.
+ *
+ * Performs a checked conversion of a #GObject to a #GripGestureManager.
+ */
+#define GRIP_GESTURE_MANAGER(obj)            (G_TYPE_CHECK_INSTANCE_CAST ((obj), GRIP_TYPE_GESTURE_MANAGER, GripGestureManager))
+
+/**
+ * GRIP_GESTURE_MANAGER_CLASS:
+ * @klass: The #GObjectClass to convert.
+ *
+ * Performes a checked conversion of a #GObjectClass to a
+ * #GripGestureManagerClass.
+ */
+#define GRIP_GESTURE_MANAGER_CLASS(klass)    (G_TYPE_CHECK_CLASS_CAST ((klass), GRIP_TYPE_GESTURE_MANAGER, GripGestureManagerClass))
+
+/**
+ * GRIP_IS_GESTURE_MANAGER:
+ * @obj: The #GObject to check.
+ *
+ * Checks to see if #GripGestureManagerClass is in the #GObjectClass heirarchy
+ * of @obj.
+ */
+#define GRIP_IS_GESTURE_MANAGER(obj)         (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GRIP_TYPE_GESTURE_MANAGER))
+
+/**
+ * GRIP_IS_GESTURE_MANAGER_CLASS:
+ * @klass: The #GObjectClass to check.
+ *
+ * Checks to see if a #GripGestureManagerClass object is in the object heirarchy
+ * of @klass.
+ */
+#define GRIP_IS_GESTURE_MANAGER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), GRIP_TYPE_GESTURE_MANAGER))
+
+/**
+ * GRIP_GESTURE_MANAGER_GET_CLASS:
+ * @obj: A #GObject.
+ *
+ * Gets the @GripGestureManagerClass object for @obj if that object is a member
+ * of its #GObjectClass heirarchy.
+ */
+#define GRIP_GESTURE_MANAGER_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS ((obj), GRIP_TYPE_GESTURE_MANAGER, GripGestureManagerClass))
 
 typedef struct _GripGestureManager        GripGestureManager;
 typedef struct _GripGestureManagerClass   GripGestureManagerClass;
@@ -48,6 +106,15 @@
 typedef struct _GripEventGestureRotate GripEventGestureRotate;
 typedef struct _GripEventGestureTap    GripEventGestureTap;
 
+/**
+ * GripGestureType:
+ * @GRIP_GESTURE_DRAG: a drag gesture
+ * @GRIP_GESTURE_PINCH: a pinch/expand gesture
+ * @GRIP_GESTURE_ROTATE: a rotate gesture
+ * @GRIP_GESTURE_TAP: a tap gesture
+ *
+ * Indicates the type of gesture for which a gesture event is being received.
+ */
 typedef enum {
   GRIP_GESTURE_DRAG    = 0,
   GRIP_GESTURE_PINCH   = 1,
@@ -55,18 +122,51 @@
   GRIP_GESTURE_TAP     = 15
 } GripGestureType;
 
+/**
+ * GripTimeType:
+ * @GRIP_TIME_START: a new gesture is starting
+ * @GRIP_TIME_UPDATE: an existing gesture is updating
+ * @GRIP_TIME_END: a gesture is ending
+ *
+ * Indicates the part of the gesture stream ocuuring during the gesture event.
+ */
 typedef enum {
   GRIP_TIME_START,
   GRIP_TIME_UPDATE,
   GRIP_TIME_END
 } GripTimeType;
 
+/**
+ * GripEventGestureAny:
+ * 
+ * This struct is not used.
+ */
 struct _GripEventGestureAny
 {
   GdkEventType  type;
   GdkWindow    *window;
 };
 
+/**
+ * GripEventGestureDrag:
+ * @type: the #GripGestureType of the gesture
+ * @id: identifies the gesture
+ * @window: the #GdkWindow in which the gesture occurred
+ * @root: the root #GdkWindow
+ * @child: the child #GdkWindow
+ * @timestamp: the time the gesture event occurred
+ * @fingers: the number of touches making up the gesture
+ * @focus_x: the X coordinate of the focus point of the gesture start
+ * @focus_y: the Y coordinate of the focus point of the gesture start
+ * @delta_x: the change in the X coordinate since the last gesture event
+ * @delta_y: the change in the Y coordinate since the last gesture event
+ * @velocity_x: the rate of change of the X coordinate
+ * @velocity_y: the rate of change of the Y coordinate
+ * @position_x: the current X coordinate of the centroid poistion of the touches
+ * @position_y: the current Y coordinate of the centroid poistion of the touches
+ *
+ * Data associated with a drag event.  A drag is a lateral motion.
+ */
 struct _GripEventGestureDrag
 {
   GripGestureType   type;
@@ -86,6 +186,25 @@
   gdouble           position_y;
 };
 
+/**
+ * GripEventGesturePinch:
+ * @type: the #GripGestureType of the gesture
+ * @id: identifies the gesture
+ * @window: the #GdkWindow in which the gesture occurred
+ * @root: the root #GdkWindow
+ * @child: the child #GdkWindow
+ * @timestamp: the time the gesture event occurred
+ * @fingers: the number of touches making up the gesture
+ * @focus_x: the X coordinate of the focus point of the gesture start
+ * @focus_y: the Y coordinate of the focus point of the gesture start
+ * @radius_delta: the change in the radius (in screen coordinates)
+ * @radial_velocity: the rate of change of the radius
+ * @radius: the current radius (in screen coordinates)
+ * @position_x: the current X coordinate of the centroid poistion of the touches
+ * @position_y: the current Y coordinate of the centroid poistion of the touches
+ *
+ * Data associated with a pinch event.  A pinch is an expand or contract motion.
+ */
 struct _GripEventGesturePinch
 {
   GripGestureType   type;
@@ -104,6 +223,25 @@
   gfloat            position_y;
 };
 
+/**
+ * GripEventGestureRotate:
+ * @type: the #GripGestureType of the gesture
+ * @id: identifies the gesture
+ * @window: the #GdkWindow in which the gesture occurred
+ * @root: the root #GdkWindow
+ * @child: the child #GdkWindow
+ * @timestamp: the time the gesture event occurred
+ * @fingers: the number of touches making up the gesture
+ * @focus_x: the X coordinate of the focus point of the gesture start
+ * @focus_y: the Y coordinate of the focus point of the gesture start
+ * @angle_delta: the change in the rotation angle (in radians) 
+ * @angular_velocity: the rate of change in the rotation angle
+ * @angle: the current rotation angle
+ * @position_x: the current X coordinate of the centroid poistion of the touches
+ * @position_y: the current Y coordinate of the centroid poistion of the touches
+ *
+ * Data associated with a rotate gesture event.
+ */
 struct _GripEventGestureRotate
 {
   GripGestureType  type;
@@ -122,6 +260,23 @@
   gfloat            position_y;
 };
 
+/**
+ * GripEventGestureTap:
+ * @type: the #GripGestureType of the gesture
+ * @id: identifies the gesture
+ * @window: the #GdkWindow in which the gesture occurred
+ * @root: the root #GdkWindow
+ * @child: the child #GdkWindow
+ * @timestamp: the time the gesture event occurred
+ * @fingers: the number of touches making up the gesture
+ * @tap_time: the duration of the tap
+ * @focus_x: the X coordinate of the focus point of the gesture start
+ * @focus_y: the Y coordinate of the focus point of the gesture start
+ * @position_x: the current X coordinate of the centroid poistion of the touches
+ * @position_y: the current Y coordinate of the centroid poistion of the touches
+ *
+ * Data associated with a tap gesture.
+ */
 struct _GripEventGestureTap
 {
   GripGestureType  type;
@@ -131,7 +286,6 @@
   GdkWindow        *child;
   guint32           timestamp;
   guint             fingers;
-
   guint32           tap_time;
   gfloat            focus_x;
   gfloat            focus_y;
@@ -139,6 +293,17 @@
   gfloat            position_y;
 };
 
+/**
+ * GripGestureEvent:
+ * @type: the #GripGestureType, selects the variant record
+ * @any: (not used)
+ * @drag: the event contains a drag gesture record
+ * @pinch: the event contains a pinch gesture record
+ * @rotate: the event contains a rotate gesture record
+ * @tap: the event contains a tap gesture record
+ *
+ * This is a boxed type.
+ */
 union _GripGestureEvent
 {
   GripGestureType        type;
@@ -150,14 +315,15 @@
 };
 
 /**
-   GripGestureManager
-   @parent: #GObject.
-
-   A singleton manager into which a window may be registered to receive
-   multitouch gesture events.
+ * GripGestureManager:
+ * @parent_instance: the parent #GObject instance.
+ *
+ * A singleton manager into which a window may be registered to receive
+ * multitouch gesture events.
  */
 struct _GripGestureManager
 {
+  /*< Public >*/
   GObject parent_instance;
 
   /*< Private >*/
@@ -165,9 +331,11 @@
 };
 
 /**
-   GripGestureManagerClass
-   @parent_class: #GObjectClass
-*/
+ * GripGestureManagerClass:
+ * @parent_class: the base #GObjectClass
+ *
+ * The class object for a #GripGestureManager.
+ */
 struct _GripGestureManagerClass
 {
   GObjectClass parent_class;
@@ -179,11 +347,19 @@
  * @time: A #GripTimeType
  * @gesture: (in): A #GripGestureEvent pointer
  * @user_data: (transfer none): user data
+ *
+ * The gesture callback function is registered by the
+ * grip_gesture_manager_register_window() function and gets called whenever a
+ * new gesture event has been received.  The same function may be registered for
+ * more than one gesture type.
+ *
+ * The <type>GripGestureCallback</type> function is the main customization point
+ * for application response to gestural input.
  **/
 typedef void (* GripGestureCallback) (GtkWidget         *widget,
                                       GripTimeType       time,
                                       GripGestureEvent  *gesture,
-                                      gpointer            user_data);
+                                      gpointer           user_data);
 
 GType                grip_gesture_manager_get_type        (void) G_GNUC_CONST;