Merge lp:~bregma/geis/improved-api-docs into lp:geis

[Stephen M. Webb]

Improved documentation, including example code using GEIS v2.

The generated documentation can be found at <http://people.canonical.com/~stephenwebb/geis-v2-api/>.

No code changes are included.

[Henrik Rydberg (rydberg)]

Love the example!

review: Approve

=== modified file '.bzrignore'
--- .bzrignore	2011-03-07 15:23:53 +0000
+++ .bzrignore	2011-03-17 04:23:22 +0000
@@ -24,6 +24,7 @@
 doc/api
 doc/docbook-xsl.css
 doc/geisspec-1.0.html
+examples/geis2
 geis_config.*
 libtool
 libutouch-geis.pc

=== modified file 'ChangeLog'
--- ChangeLog	2011-03-16 21:56:03 +0000
+++ ChangeLog	2011-03-17 04:23:22 +0000
@@ -1,5 +1,19 @@
 2011-03-16  Stephen M. Webb  <[e-mail]>
 
+  Refined the API documentation and added an examples directory.
+
+  * doc/api.dox: new documentation file
+  * doc/logo_x64.png: new logo image
+  * doc/using_geis_v2.dox: new documentation file
+  * examples/Makefile.am: examples subdirectory Makefile
+  * examples/geis2.c: new example program
+  * Makefile.am: added examples subdirectory
+  * configure.ac: added examples subdirectory
+  * doc/Doxyfile: tweaked Doxygen settings
+  * include/geis/geis.h: complete API docs refinement
+
[phone]  Stephen M. Webb  <[e-mail]>
+
   Replaced device class with explicit attributes.
 
   * include/geis/geis.h (GEIS_DEVICE_CLASS_*) removed

=== modified file 'Makefile.am'
--- Makefile.am	2011-02-08 03:26:22 +0000
+++ Makefile.am	2011-03-17 04:23:22 +0000
@@ -21,7 +21,7 @@
 
 ACLOCAL_MFLAGS = -I m4
 
-SUBDIRS = include libs libutouch-geis testsuite doc
+SUBDIRS = include libs libutouch-geis testsuite examples doc
 
 doc-%:
 	$(MAKE) -C doc $@

=== modified file 'configure.ac'
--- configure.ac	2011-03-09 19:46:45 +0000
+++ configure.ac	2011-03-17 04:23:22 +0000
@@ -96,5 +96,6 @@
                  testsuite/libutouch-geis/Makefile
                  testsuite/geis2/Makefile
                  testsuite/geis1/Makefile
-                 testsuite/geistest/Makefile])
+                 testsuite/geistest/Makefile
+                 examples/Makefile])
 AC_OUTPUT

=== modified file 'doc/Doxyfile'
--- doc/Doxyfile	2011-03-12 02:52:56 +0000
+++ doc/Doxyfile	2011-03-17 04:23:22 +0000
@@ -1,4 +1,4 @@
-# Doxyfile 1.7.1
+# Doxyfile 1.7.3
 
 # This file describes the settings to be used by the documentation system
 # doxygen (www.doxygen.org) for a project
@@ -31,7 +31,20 @@
 # This could be handy for archiving the generated documentation or 
 # if some version control system is used.
 
-PROJECT_NUMBER         = 0.3
+PROJECT_NUMBER         = 2.0
+
+# Using the PROJECT_BRIEF tag one can provide an optional one line description
+# for a project that appears at the top of each page and should give viewer
+# a quick idea about the purpose of the project. Keep the description short.
+
+PROJECT_BRIEF          = "Gesture Engine Interface Support"
+
+# With the PROJECT_LOGO tag one can specify an logo or icon that is 
+# included in the documentation. The maximum height of the logo should not 
+# exceed 55 pixels and the maximum width should not exceed 200 pixels. 
+# Doxygen will copy the logo to the output directory.
+
+PROJECT_LOGO           = logo_x64.png
 
 # The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) 
 # base path where the generated documentation will be put. 
@@ -57,7 +70,7 @@
 # Croatian, Czech, Danish, Dutch, Esperanto, Farsi, Finnish, French, German, 
 # Greek, Hungarian, Italian, Japanese, Japanese-en (Japanese with English 
 # messages), Korean, Korean-en, Lithuanian, Norwegian, Macedonian, Persian, 
-# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrilic, Slovak, 
+# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrillic, Slovak, 
 # Slovene, Spanish, Swedish, Ukrainian, and Vietnamese.
 
 OUTPUT_LANGUAGE        = English
@@ -136,7 +149,7 @@
 STRIP_FROM_INC_PATH    = 
 
 # If the SHORT_NAMES tag is set to YES, doxygen will generate much shorter 
-# (but less readable) file names. This can be useful is your file systems 
+# (but less readable) file names. This can be useful if your file system 
 # doesn't support long names like on DOS, Mac, or CD-ROM.
 
 SHORT_NAMES            = NO
@@ -147,7 +160,7 @@
 # comments will behave just like regular Qt-style comments 
 # (thus requiring an explicit @brief command for a brief description.)
 
-JAVADOC_AUTOBRIEF      = NO
+JAVADOC_AUTOBRIEF      = YES
 
 # If the QT_AUTOBRIEF tag is set to YES then Doxygen will 
 # interpret the first line (until the first dot) of a Qt-style 
@@ -233,7 +246,7 @@
 # to include (a tag file for) the STL sources as input, then you should 
 # set this tag to YES in order to let doxygen match functions declarations and 
 # definitions whose arguments contain STL classes (e.g. func(std::string); v.s. 
-# func(std::string) {}). This also make the inheritance and collaboration 
+# func(std::string) {}). This also makes the inheritance and collaboration 
 # diagrams that involve STL classes more complete and accurate.
 
 BUILTIN_STL_SUPPORT    = NO
@@ -251,7 +264,7 @@
 
 # For Microsoft's IDL there are propget and propput attributes to indicate getter 
 # and setter methods for a property. Setting this option to YES (the default) 
-# will make doxygen to replace the get and set methods by a property in the 
+# will make doxygen replace the get and set methods by a property in the 
 # documentation. This will only work if the methods are indeed getting or 
 # setting a simple type. If this is not the case, or you want to show the 
 # methods anyway, you should set this option to NO.
@@ -289,10 +302,10 @@
 # For small to medium size projects (<1000 input files) the default value is 
 # probably good enough. For larger projects a too small cache size can cause 
 # doxygen to be busy swapping symbols to and from disk most of the time 
-# causing a significant performance penality. 
+# causing a significant performance penalty. 
 # If the system has enough physical memory increasing the cache will improve the 
 # performance by keeping more symbols in memory. Note that the value works on 
-# a logarithmic scale so increasing the size by one will rougly double the 
+# a logarithmic scale so increasing the size by one will roughly double the 
 # memory usage. The cache size is given by this formula: 
 # 2^(16+SYMBOL_CACHE_SIZE). The valid range is 0..9, the default is 0, 
 # corresponding to a cache size of 2^16 = 65536 symbols
@@ -337,7 +350,7 @@
 # extracted and appear in the documentation as a namespace called 
 # 'anonymous_namespace{file}', where file will be replaced with the base 
 # name of the file that contains the anonymous namespace. By default 
-# anonymous namespace are hidden.
+# anonymous namespaces are hidden.
 
 EXTRACT_ANON_NSPACES   = NO
 
@@ -448,6 +461,15 @@
 
 SORT_BY_SCOPE_NAME     = NO
 
+# If the STRICT_PROTO_MATCHING option is enabled and doxygen fails to
+# do proper type resolution of all parameters of a function it will reject a 
+# match between the prototype and the implementation of a member function even
+# if there is only one candidate or it is obvious which candidate to choose
+# by doing a simple string match. By disabling STRICT_PROTO_MATCHING doxygen 
+# will still accept a match between prototype and implementation in such cases.
+
+STRICT_PROTO_MATCHING  = NO
+
 # The GENERATE_TODOLIST tag can be used to enable (YES) or 
 # disable (NO) the todo list. This list is created by putting \todo 
 # commands in the documentation.
@@ -478,14 +500,14 @@
 ENABLED_SECTIONS       = 
 
 # The MAX_INITIALIZER_LINES tag determines the maximum number of lines 
-# the initial value of a variable or define consists of for it to appear in 
+# the initial value of a variable or macro consists of for it to appear in 
 # the documentation. If the initializer consists of more lines than specified 
 # here it will be hidden. Use a value of 0 to hide initializers completely. 
-# The appearance of the initializer of individual variables and defines in the 
+# The appearance of the initializer of individual variables and macros in the 
 # documentation can be controlled using \showinitializer or \hideinitializer 
 # command in the documentation regardless of this setting.
 
-MAX_INITIALIZER_LINES  = 30
+MAX_INITIALIZER_LINES  = 0
 
 # Set the SHOW_USED_FILES tag to NO to disable the list of files generated 
 # at the bottom of the documentation of classes and structs. If set to YES the 
@@ -558,7 +580,7 @@
 
 WARN_IF_DOC_ERROR      = YES
 
-# This WARN_NO_PARAMDOC option can be abled to get warnings for 
+# The WARN_NO_PARAMDOC option can be enabled to get warnings for 
 # functions that are documented, but have no documentation for their parameters 
 # or return value. If set to NO (the default) doxygen will only warn about 
 # wrong or incomplete parameter documentation, but not about the absence of 
@@ -590,7 +612,8 @@
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = ../include/geis
+INPUT                  = ../include/geis \
+                         .
 
 # This tag can be used to specify the character encoding of the source files 
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is 
@@ -604,8 +627,9 @@
 # FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 
 # and *.h) to filter out the source-files in the directories. If left 
 # blank the following patterns are tested: 
-# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx 
-# *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.py *.f90
+# *.c *.cc *.cxx *.cpp *.c++ *.d *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh 
+# *.hxx *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.dox *.py 
+# *.f90 *.f *.for *.vhd *.vhdl
 
 FILE_PATTERNS          = *.c \
                          *.cc \
@@ -637,7 +661,8 @@
                          *.f90 \
                          *.f \
                          *.vhd \
-                         *.vhdl
+                         *.vhdl \
+                         *.dox
 
 # The RECURSIVE tag can be used to turn specify whether or not subdirectories 
 # should be searched for input files as well. Possible values are YES and NO. 
@@ -652,7 +677,7 @@
 EXCLUDE                = 
 
 # The EXCLUDE_SYMLINKS tag can be used select whether or not files or 
-# directories that are symbolic links (a Unix filesystem feature) are excluded 
+# directories that are symbolic links (a Unix file system feature) are excluded 
 # from the input.
 
 EXCLUDE_SYMLINKS       = NO
@@ -677,7 +702,7 @@
 # directories that contain example code fragments that are included (see 
 # the \include command).
 
-EXAMPLE_PATH           = 
+EXAMPLE_PATH           = ../examples
 
 # If the value of the EXAMPLE_PATH tag contains directories, you can use the 
 # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp 
@@ -713,8 +738,8 @@
 # basis.  Doxygen will compare the file name with each pattern and apply the 
 # filter if there is a match.  The filters are a list of the form: 
 # pattern=filter (like *.cpp=my_cpp_filter). See INPUT_FILTER for further 
-# info on how filters are used. If FILTER_PATTERNS is empty, INPUT_FILTER 
-# is applied to all files.
+# info on how filters are used. If FILTER_PATTERNS is empty or if 
+# non of the patterns match the file name, INPUT_FILTER is applied.
 
 FILTER_PATTERNS        = 
 
@@ -724,6 +749,14 @@
 
 FILTER_SOURCE_FILES    = NO
 
+# The FILTER_SOURCE_PATTERNS tag can be used to specify source filters per file 
+# pattern. A pattern will override the setting for FILTER_PATTERN (if any) 
+# and it is also possible to disable source filtering for a specific pattern 
+# using *.ext= (so without naming a filter). This option only has effect when 
+# FILTER_SOURCE_FILES is enabled.
+
+FILTER_SOURCE_PATTERNS = 
+
 #---------------------------------------------------------------------------
 # configuration options related to source browsing
 #---------------------------------------------------------------------------
@@ -777,7 +810,7 @@
 # will generate a verbatim copy of the header file for each class for 
 # which an include is specified. Set to NO to disable this.
 
-VERBATIM_HEADERS       = YES
+VERBATIM_HEADERS       = NO
 
 #---------------------------------------------------------------------------
 # configuration options related to the alphabetical class index
@@ -1046,8 +1079,10 @@
 
 DISABLE_INDEX          = NO
 
-# This tag can be used to set the number of enum values (range [1..20]) 
-# that doxygen will group on one line in the generated HTML documentation.
+# This tag can be used to set the number of enum values (range [0,1..20]) 
+# that doxygen will group on one line in the generated HTML documentation. 
+# Note that a value of 0 will completely suppress the enum values from
+# appearing in the overview section.
 
 ENUM_VALUES_PER_LINE   = 4
 
@@ -1093,6 +1128,26 @@
 
 FORMULA_TRANSPARENT    = YES
 
+# Enable the USE_MATHJAX option to render LaTeX formulas using MathJax 
+# (see http://www.mathjax.org) which uses client side Javascript for the 
+# rendering instead of using prerendered bitmaps. Use this if you do not 
+# have LaTeX installed or if you want to formulas look prettier in the HTML 
+# output. When enabled you also need to install MathJax separately and 
+# configure the path to it using the MATHJAX_RELPATH option.
+
+USE_MATHJAX            = NO
+
+# When MathJax is enabled you need to specify the location relative to the 
+# HTML output directory using the MATHJAX_RELPATH option. The destination 
+# directory should contain the MathJax.js script. For instance, if the mathjax 
+# directory is located at the same level as the HTML output directory, then 
+# MATHJAX_RELPATH should be ../mathjax. The default value points to the
+# mathjax.org site, so you can quickly see the result without installing 
+# MathJax, but it is strongly recommended to install a local copy of MathJax 
+# before deployment.
+
+MATHJAX_RELPATH        = http://www.mathjax.org/mathjax
+
 # When the SEARCHENGINE tag is enabled doxygen will generate a search box 
 # for the HTML output. The underlying search engine uses javascript 
 # and DHTML and should work on any modern browser. Note that when using 
@@ -1108,7 +1163,7 @@
 # using Javascript. Doxygen will generate the search PHP script and index 
 # file to put on the web server. The advantage of the server 
 # based approach is that it scales better to large projects and allows 
-# full text search. The disadvances is that it is more difficult to setup 
+# full text search. The disadvantages are that it is more difficult to setup 
 # and does not have live searching capabilities.
 
 SERVER_BASED_SEARCH    = NO
@@ -1149,7 +1204,7 @@
 COMPACT_LATEX          = NO
 
 # The PAPER_TYPE tag can be used to set the paper type that is used 
-# by the printer. Possible values are: a4, a4wide, letter, legal and 
+# by the printer. Possible values are: a4, letter, legal and 
 # executive. If left blank a4wide will be used.
 
 PAPER_TYPE             = a4wide
@@ -1364,13 +1419,13 @@
 # compilation will be performed. Macro expansion can be done in a controlled 
 # way by setting EXPAND_ONLY_PREDEF to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES 
 # then the macro expansion is limited to the macros specified with the 
 # PREDEFINED and EXPAND_AS_DEFINED tags.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES (the default) the includes files 
 # in the INCLUDE_PATH (see below) will be search if a #include is found.
@@ -1398,20 +1453,20 @@
 # undefined via #undef or recursively expanded use the := operator 
 # instead of the = operator.
 
-PREDEFINED             = GEIS_API=""
+PREDEFINED             = GEIS_API=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then 
 # this tag can be used to specify a list of macro names that should be expanded. 
 # The macro definition that is found in the sources will be used. 
-# Use the PREDEFINED tag if you want to use a different macro definition.
+# Use the PREDEFINED tag if you want to use a different macro definition that
+# overrules the definition found in the source code.
 
 EXPAND_AS_DEFINED      = 
 
 # If the SKIP_FUNCTION_MACROS tag is set to YES (the default) then 
-# doxygen's preprocessor will remove all function-like macros that are alone 
-# on a line, have an all uppercase name, and do not end with a semicolon. Such 
-# function macros are typically used for boiler-plate code, and will confuse 
-# the parser if not removed.
+# doxygen's preprocessor will remove all references to function-like macros 
+# that are alone on a line, have an all uppercase name, and do not end with a 
+# semicolon, because these will confuse the parser if not removed.
 
 SKIP_FUNCTION_MACROS   = YES
 
@@ -1465,9 +1520,8 @@
 # If the CLASS_DIAGRAMS tag is set to YES (the default) Doxygen will 
 # generate a inheritance diagram (in HTML, RTF and LaTeX) for classes with base 
 # or super classes. Setting the tag to NO turns the diagrams off. Note that 
-# this option is superseded by the HAVE_DOT option below. This is only a 
-# fallback. It is recommended to install and use dot, since it yields more 
-# powerful graphs.
+# this option also works with HAVE_DOT disabled, but it is recommended to 
+# install and use dot, since it yields more powerful graphs.
 
 CLASS_DIAGRAMS         = YES
 
@@ -1501,11 +1555,10 @@
 
 DOT_NUM_THREADS        = 0
 
-# By default doxygen will write a font called FreeSans.ttf to the output 
-# directory and reference it in all dot files that doxygen generates. This 
-# font does not include all possible unicode characters however, so when you need 
-# these (or just want a differently looking font) you can specify the font name 
-# using DOT_FONTNAME. You need need to make sure dot is able to find the font, 
+# By default doxygen will write a font called Helvetica to the output 
+# directory and reference it in all dot files that doxygen generates. 
+# When you want a differently looking font you can specify the font name 
+# using DOT_FONTNAME. You need to make sure dot is able to find the font, 
 # which can be done by putting it in a standard location or by setting the 
 # DOTFONTPATH environment variable or by setting DOT_FONTPATH to the directory 
 # containing the font.
@@ -1585,7 +1638,7 @@
 CALLER_GRAPH           = NO
 
 # If the GRAPHICAL_HIERARCHY and HAVE_DOT tags are set to YES then doxygen 
-# will graphical hierarchy of all classes instead of a textual one.
+# will generate a graphical hierarchy of all classes instead of a textual one.
 
 GRAPHICAL_HIERARCHY    = YES
 
@@ -1597,7 +1650,7 @@
 DIRECTORY_GRAPH        = YES
 
 # The DOT_IMAGE_FORMAT tag can be used to set the image format of the images 
-# generated by dot. Possible values are png, jpg, or gif 
+# generated by dot. Possible values are png, svg, gif or svg. 
 # If left blank png will be used.
 
 DOT_IMAGE_FORMAT       = png
@@ -1613,6 +1666,12 @@
 
 DOTFILE_DIRS           = 
 
+# The MSCFILE_DIRS tag can be used to specify one or more directories that 
+# contain msc files that are included in the documentation (see the 
+# \mscfile command).
+
+MSCFILE_DIRS           = 
+
 # The DOT_GRAPH_MAX_NODES tag can be used to set the maximum number of 
 # nodes that will be shown in the graph. If the number of nodes in a graph 
 # becomes larger than this value, doxygen will truncate the graph, which is 

=== added file 'doc/api.dox'
--- doc/api.dox	1970-01-01 00:00:00 +0000
+++ doc/api.dox	2011-03-17 04:23:22 +0000
@@ -0,0 +1,21 @@
+/**
+ * @mainpage The GEIS API
+ *
+ * @section sec_intro Introduction
+ *
+ * The GEIS API provides a defined, stable, portable interface for receiving
+ * gestural input.
+ *
+ * GEIS actually provides two APIs:
+ * the @ref using_geis_v1 "simplified interface"
+ * and the @ref using_geis_v2 "advanced interface".
+ *
+ * @page  using_geis_v1 Using The Simplified Interface
+ *
+ * @section using_geis_v1_intro Introduction to the Simplified GEIS Interface
+ *
+ * The goal of the simplified GEIS interface is to minimize the work required to
+ * receive gestures from the gesture recognition engine.  It is designed around
+ * the idea of creating a set of callback functions and installing them to
+ * receive gesture events on a selected window.
+ */

=== added file 'doc/logo_x64.png'
Binary files doc/logo_x64.png	1970-01-01 00:00:00 +0000 and doc/logo_x64.png	2011-03-17 04:23:22 +0000 differ
=== added file 'doc/using_geis_v2.dox'
--- doc/using_geis_v2.dox	1970-01-01 00:00:00 +0000
+++ doc/using_geis_v2.dox	2011-03-17 04:23:22 +0000
@@ -0,0 +1,78 @@
+/**
+
+@page using_geis_v2 Using The Advanced Interface
+ 
+@section using_geis_v2_intro Introduction to the Advanced GEIS Interface
+
+The advanced GEIS interface is designed around the idea that you can create
+<em>filters</em> to limit the kinds of gestures received and combine those
+filters into <em>subscriptions</em> that interact  with the gesture
+recognizer to deliver <em>gesture events</em>.
+
+The normal flow for using the advanced interface is as follows.
+  -# create a Geis object
+  -# create a GeisSubscription object on the Geis object
+  -# create and add one or more GeisFilter to the GeisSubscription
+  -# activate the GeisSubscription
+  -# wait for and process a series of GeisEvent
+
+@subsection using_geis_v2_example An example of advanced API usage
+This is an example of using the advanced (GEIS v2) API.  The full source code
+for this example (including details missing here) is included in the source
+distribution of utouch-geis.
+
+Please note that these examples omit all of the error checking for expository
+purposes only.  
+
+@dontinclude geis2.c
+
+First, some objects are declared.
+@skip GeisStatus
+@until int
+
+The API instance is created.  We tell it to report input devices and gesture
+classes.
+@until NULL
+
+A subscription object is created.  We want gesture continuations.
+@line geis_subscription_new
+
+An empty filter is created.  An empty filter means <em>all</em> input devices,
+<em>all</em> gestures, <em>all</em> regions.
+@line geis_filter_new
+
+For the purpose of this example, we want just 2-touch gestures, so we need to
+add a term to the filter specifying only those gestures with two touches.
+@skip geis_filter_add_term
+@until NULL
+
+The filter is added to the subscription and the subscription is activated.
+@until geis_subscription_activate
+
+For the event loop processing, we're going to need the event fd (this is
+assuming a Unix implementation of GEIS, other platforms may have a different
+event indicator).
+@line geis_get_configuration
+
+The application's main event loop is run until a read is indicated as available
+on the event fd, at which point the GEIS event loop is pumped.
+@skip geis_dispatch_events
+@until geis_next_event
+The events are handled and the event loop pumped until it's empty.
+@until geis_next_event
+
+Finally, the API objects are cleaned up.
+@skip geis_subscription_delete
+@until geis_delete
+
+@subsection using_geis_v2_examining_devices Examining Devices
+
+@dontinclude geis2.c
+
+@skip dump_device_event
+@until }
+@line }
+
+@example geis2.c
+
+*/

=== added directory 'examples'
=== added file 'examples/Makefile.am'
--- examples/Makefile.am	1970-01-01 00:00:00 +0000
+++ examples/Makefile.am	2011-03-17 04:23:22 +0000
@@ -0,0 +1,28 @@
+#
+# @file examples/Makefile.am 
+# @brief automake recipe for the GEIS examples
+#
+# Copyright 2011 Canonical, Ltd.
+#
+# This file is part of the utouch-geis library. This library is free software;
+# you can redistribute it and/or modify it under the terms of the GNU Lesser
+# General Public License as published by the Free Software Foundation; either
+# version 3 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+# FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more
+# details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+
+noinst_PROGRAMS = geis2
+
+geis2_SOURCES = geis2.c
+
+geis2_CFLAGS = -I$(top_srcdir)/include -I$(top_srcdir)/libutouch-geis
+
+geis2_LDADD = $(top_builddir)/libutouch-geis/libutouch-geis.la
+

=== added file 'examples/geis2.c'
--- examples/geis2.c	1970-01-01 00:00:00 +0000
+++ examples/geis2.c	2011-03-17 04:23:22 +0000
@@ -0,0 +1,190 @@
+/**
+ * @file geis2.c
+ * @brief A simple example using the GEIS v2 API.
+ *
+ * Copyright 2011 Canonical Ltd.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include <errno.h>
+#include <geis/geis.h>
+#include <stdio.h>
+#include <string.h>
+#include <sys/select.h>
+
+
+void print_attr(GeisAttr attr)
+{
+  GeisString attr_name = geis_attr_name(attr);
+  switch (geis_attr_type(attr))
+  {
+    case GEIS_ATTR_TYPE_BOOLEAN:
+      printf("  \"%s\": %s\n", attr_name,
+             geis_attr_value_to_boolean(attr) ? "true" : "false");
+      break;
+    case GEIS_ATTR_TYPE_FLOAT:
+      printf("  \"%s\": %g\n", attr_name, geis_attr_value_to_float(attr));
+      break;
+    case GEIS_ATTR_TYPE_INTEGER:
+      printf("  \"%s\": %d\n", attr_name, geis_attr_value_to_integer(attr));
+      break;
+    case GEIS_ATTR_TYPE_STRING:
+      printf("  \"%s\": %s\n", attr_name, geis_attr_value_to_string(attr));
+      break;
+    default:
+      break;
+  }
+}
+
+
+void
+dump_device_event(GeisEvent event)
+{
+  GeisDevice device;
+  GeisAttr attr;
+  GeisSize i;
+  GeisInputDeviceId device_id = 0;
+
+  attr = geis_event_attr_by_name(event, GEIS_EVENT_ATTRIBUTE_DEVICE);
+  device = geis_attr_value_to_pointer(attr);
+  printf("device %02d \"%s\"\n",
+         geis_device_id(device), geis_device_name(device));
+  for (i = 0; i < geis_device_attr_count(device); ++i)
+  {
+    print_attr(geis_device_attr(device, i));
+  }
+}
+
+
+void
+dump_gesture_event(GeisEvent event)
+{
+  GeisSize i;
+  GeisTouchSet touchset;
+  GeisGroupSet groupset;
+  GeisAttr     attr;
+
+  attr = geis_event_attr_by_name(event, GEIS_EVENT_ATTRIBUTE_TOUCHSET);
+  touchset = geis_attr_value_to_pointer(attr);
+
+  attr = geis_event_attr_by_name(event, GEIS_EVENT_ATTRIBUTE_GROUPSET);
+  groupset = geis_attr_value_to_pointer(attr);
+
+  printf("gesture\n");
+  for (i= 0; i < geis_groupset_group_count(groupset); ++i)
+  {
+    GeisSize j;
+    GeisGroup group = geis_groupset_group(groupset, i);
+
+    for (j=0; j < geis_group_frame_count(group); ++j)
+    {
+      GeisSize k;
+      GeisFrame frame = geis_group_frame(group, j);
+      GeisSize attr_count = geis_frame_attr_count(frame);
+
+      for (k = 0; k < attr_count; ++k)
+      {
+	print_attr(geis_frame_attr(frame, k));
+      }
+
+      for (k = 0; k < geis_frame_touchid_count(frame); ++k)
+      {
+	GeisSize  touchid = geis_frame_touchid(frame, k);
+	GeisTouch touch = geis_touchset_touch_by_id(touchset, touchid);
+	GeisSize  n;
+	printf("+touch %lu\n", k);
+	for (n = 0; n < geis_touch_attr_count(touch); ++n)
+	{
+	  print_attr(geis_touch_attr(touch, n));
+	}
+      }
+    }
+  }
+}
+
+
+int
+main(int argc, char* argv[])
+{
+  GeisStatus status;
+  Geis geis;
+  GeisSubscription subscription;
+  GeisFilter filter;
+  int        fd;
+
+  geis = geis_new(GEIS_INIT_UTOUCH_XCB,
+                  GEIS_INIT_TRACK_DEVICES,
+                  NULL);
+  subscription = geis_subscription_new(geis, "example", GEIS_SUBSCRIPTION_CONT);
+  filter = geis_filter_new(geis, "filter");
+
+  geis_filter_add_term(filter,
+                       GEIS_FILTER_REGION,
+                       GEIS_GESTURE_ATTRIBUTE_TOUCHES, GEIS_FILTER_OP_EQ, 2,
+                       NULL);
+
+  status = geis_subscription_add_filter(subscription, filter);
+  status = geis_subscription_activate(subscription);
+
+  geis_get_configuration(geis, GEIS_CONFIGURATION_FD, &fd);
+
+  while(1)
+  {
+    fd_set read_fds;
+    FD_ZERO(&read_fds);
+    FD_SET(0, &read_fds);
+    FD_SET(fd, &read_fds);
+    int sstat = select(fd+1, &read_fds, NULL, NULL, NULL);
+    if (sstat < 0)
+    {
+      fprintf(stderr, "error %d in select(): %s\n", errno, strerror(errno));
+      break;
+    }
+
+    if (FD_ISSET(fd, &read_fds))
+    {
+      GeisEvent event;
+      status = geis_dispatch_events(geis);
+      status = geis_next_event(geis, &event);
+      while (status == GEIS_STATUS_CONTINUE || status == GEIS_STATUS_SUCCESS)
+      {
+	switch (geis_event_type(event))
+	{
+	  case GEIS_EVENT_DEVICE_AVAILABLE:
+	  case GEIS_EVENT_DEVICE_UNAVAILABLE:
+	    dump_device_event(event);
+	    break;
+
+	  case GEIS_EVENT_GESTURE_BEGIN:
+	  case GEIS_EVENT_GESTURE_UPDATE:
+	  case GEIS_EVENT_GESTURE_END:
+	    dump_gesture_event(event);
+	    break;
+	}
+	geis_event_delete(event);
+	status = geis_next_event(geis, &event);
+      }
+    }
+
+    if (FD_ISSET(0, &read_fds))
+    {
+      break;
+    }
+  }
+
+  geis_subscription_delete(subscription);
+  geis_delete(geis);
+}
+

=== modified file 'include/geis/geis.h'
--- include/geis/geis.h	2011-03-16 21:56:03 +0000
+++ include/geis/geis.h	2011-03-17 04:23:22 +0000
@@ -25,11 +25,83 @@
 extern "C" {
 #endif
 
+/**
+ * @defgroup geis_common Common Types and Definitions
+ *
+ * These types and values are common to both the simplified and advanced GEIS
+ * interfaces.
+ */
+
+/**
+  * @defgroup geis_v1 The Simplified GEIS Interface
+  *
+  * The simplified GEIS interface is the original (GEIS v1) API.  It provides a
+  * way to specify a list of gesture names and input devices for which gestures
+  * will be recognized on a given window.
+  *
+  * See @ref using_geis_v1.
+  */
+
+/**
+ * @defgroup geis_v2 The Advanced GEIS Interface
+ *
+ * The advanced GEIS interface (GEIS v2) was developed to give a more nuanced
+ * control over the types of gestures and input devices for which gestures will
+ * be recognized.
+  *
+  * See @ref using_geis_v2.
+ */
+
+/**
+  * GEIS version macros
+  *
+  * These macros can be tested at compile time to query for support of various
+  * features.
+  */
 #define GEIS_VERSION_1_0  1
 #define GEIS_VERSION_2_0  20101122
 
 #include <geis/geisimpl.h>
 
+/**
+ * Errors returned from calls.
+ * @ingroup geis_common
+ *
+ * Most GEIS API calls return a status code indicating success or, in the event
+ * of a lack of success, the reson for failure.
+ */
+typedef enum GeisStatus
+{
+  GEIS_STATUS_SUCCESS       = 0,    /**< normal successful completion */
+  GEIS_STATUS_CONTINUE      = 20,   /**< normal successful completion
+                                         with data still remaining */
+  GEIS_STATUS_EMPTY         = 21,   /**< normal successful completion
+                                         with no data retrieved */
+  GEIS_STATUS_NOT_SUPPORTED = 10,   /**< a requested feature is not supported */
+  GEIS_BAD_ARGUMENT         = 1000, /**< a bad argument value was passed */
+  GEIS_UNKNOWN_ERROR        = 9999, /**< any other error condition */
+  GEIS_STATUS_BAD_ARGUMENT  = -100, /**< a bad argument value was passed */
+  GEIS_STATUS_UNKNOWN_ERROR = -999  /**< any other error condition */
+} GeisStatus;
+
+/**
+ * Attribute data types.
+ * @ingroup geis_common
+ */
+typedef enum GeisAttrType
+{
+  GEIS_ATTR_TYPE_UNKNOWN,    /**< Attr is an unknown type. */
+  GEIS_ATTR_TYPE_BOOLEAN,    /**< Attr is truth-valued . */
+  GEIS_ATTR_TYPE_FLOAT,      /**< Attr is real-valued. */
+  GEIS_ATTR_TYPE_INTEGER,    /**< Attr is a counting number. */
+  GEIS_ATTR_TYPE_POINTER,    /**< Attr is a pointer to a data structure. */
+  GEIS_ATTR_TYPE_STRING      /**< Attr is a null-terminated UTF-8 string. */
+
+} GeisAttrType;
+
+#define GEIS_FALSE 0
+#define GEIS_TRUE  1
+
 /* Standard fundamental gestures */
 #define GEIS_GESTURE_DRAG    "Drag"
 #define GEIS_GESTURE_PINCH   "Pinch"
@@ -37,10 +109,20 @@
 #define GEIS_GESTURE_TAP     "Tap"
 
 /**
- * @defgroup geis_v1_gesture_types Standard Gesture Types (GEIS v1)
- * The names of standard gesture types.  These names can be passed to 
+ * @defgroup geis_v1_gesture_types Gesture Types
+ * @ingroup geis_v1
+ *
+ * The names of gesture types.  These names can be passed to 
  * geis_subscribe() in a NULL-terminated list to specify only a subset of
  * available gestures.
+ */
+
+/**
+ * @defgroup geis_v1_standar_gesture_types Standard Gesture Types
+ * @ingroup geis_v1_gesture_types
+ *
+ * These gesture types should be available on all GEIS implementations.
+ *
  * @{
  */
 
@@ -69,8 +151,11 @@
 /* @} */
 
 /**
- * @defgroup geis_v1_vendor_extensions Vendor Extensions (GEIS v1)
+ * @defgroup geis_v1_vendor_extensions Vendor Extension Gesture Types
+ * @ingroup geis_v1_gesture_types
+ *
  * Vendor-specific extensions to the GEIS v1 API.
+ *
  * @{
  */
 
@@ -124,46 +209,10 @@
 #define GEIS_GESTURE_ATTRIBUTE_TOUCH_4_X        "touch 4 x"
 #define GEIS_GESTURE_ATTRIBUTE_TOUCH_4_Y        "touch 4 y"
 
-#define GEIS_TOUCH_ATTRIBUTE_ID                 "touch id"
-#define GEIS_TOUCH_ATTRIBUTE_X                  "touch x"
-#define GEIS_TOUCH_ATTRIBUTE_Y                  "touch y"
-
-#define GEIS_REGION_ATTRIBUTE_WINDOWID          "windowid"
-
-#define GEIS_FALSE 0
-#define GEIS_TRUE  1
-
-
-/**
- * @defgroup geis_status Status and Errors
- *
- * Most GEIS API calls return a status code indicating success or, in the event
- * of a lack of success, the reson for failure.
- *
- * @{
- */
-
-/**
- * Errors returned from calls.
- */
-typedef enum GeisStatus
-{
-  GEIS_STATUS_SUCCESS       = 0,    /**< normal successful completion */
-  GEIS_STATUS_CONTINUE      = 20,   /**< normal successful completion
-                                         with data still remaining */
-  GEIS_STATUS_EMPTY         = 21,   /**< normal successful completion
-                                         with no data retrieved */
-  GEIS_STATUS_NOT_SUPPORTED = 10,   /**< a requested feature is not supported */
-  GEIS_BAD_ARGUMENT         = 1000, /**< a bad argument value was passed */
-  GEIS_UNKNOWN_ERROR        = 9999, /**< any other error condition */
-  GEIS_STATUS_BAD_ARGUMENT  = -100, /**< a bad argument value was passed */
-  GEIS_STATUS_UNKNOWN_ERROR = -999  /**< any other error condition */
-} GeisStatus;
-
-/* @} */
 
 /**
  * @defgroup geis_meta Initialization and Cleanup
+ * @ingroup geis_v1
  *
  * Each instance of a gesture subscription must be created using the geis_init()
  * call and destroyed using the geis_finish() call.
@@ -182,22 +231,26 @@
  */
 
 /**
- * An opaque type representing a geis gesture subscription instance.
+ * @class GeisInstance
+ * A geis gesture subscription instance.
  */
+/** @cond typedef */
 typedef struct _GeisInstance *GeisInstance;
+/** @endcond */
 
 /**
- * @struct GeisWinInfo
+ * @class GeisWinInfo
  * Generic display region description block
  */
 typedef struct GeisWinInfo
 {
-  uint32_t win_type;
-  void    *win_info;
+  uint32_t win_type;    /**< Selects the implementation-specific window type. */
+  void    *win_info;    /**< Additional info dependent on the window type. */
 } GeisWinInfo;
 
 /**
  * Initializes a geis subscription instance for a display region.
+ * @memberof GeisInstance
  *
  * @param[in]  win_info         a display region description block
  *                              -- see geis implementtaion documentation
@@ -210,7 +263,8 @@
 GEIS_API GeisStatus geis_init(GeisWinInfo *win_info, GeisInstance *geis_instance);
 
 /**
- * Cleans up a geis subscriotion instance for a display region.
+ * Cleans up a geis subscription instance for a display region.
+ * @memberof GeisInstance
  *
  * @param[in] geis_instance     an opaque pointer to a geis gesture subscription
  *                              instance
@@ -223,49 +277,139 @@
 /* @} */
 
 /**
- * @defgroup geis_2_geis The Geis API Object (GEIS v2.0)
- *
- * @{
- */
-
-/**
- * @defgroup geis_2_geis_init_args Specified Initialization Arguments
- *
- * These initialization arguments are defined by the GEIS specification.
- *
- * @{
- */
-
-/**
+ * @defgroup geis_v1_config Configuration and Control
+ * @ingroup geis_v1
+ * @{
+ */
+
+/**
+ * Gets the Unix file descriptor for GEIS events.
+ *
+ * Applications or toolkits can use this file descriptor to intgerate geis event
+ * handling into their main event dispatch loop.  When a GEIS event is available
+ * for processing, the fd will have a read-available state indicated in
+ * select(), poll(), epoll(), etc.
+ */
+#define GEIS_CONFIG_UNIX_FD 10001
+
+/**
+ * Indicates if a particular feaure is supported.
+ *
+ * @param[in] geis_instance      An opaque pointer to a geis gesture subscription
+ *                               instance.
+ * @param[in] configuration_item Indicates which configuration item will be
+ *                               checked for support.
+ *
+ * @retval GEIS_BAD_ARGUMENT    an invalid argument value was passed
+ * @retval GEIS_STATUS_SUCCESS  normal successful completion
+ */
+GEIS_API GeisStatus geis_configuration_supported(GeisInstance geis_instance,
+                                                 int          configuration_item);
+
+/**
+ * Gets a feature configuration value.
+ *
+ * @param[in] geis_instance      An opaque pointer to a geis gesture subscription
+ *                               instance.
+ * @param[in] configuration_item Indicates which configuration item will be
+ *                               get.
+ * @param[in] value              A pointer to where the retrieved value will be
+ *                               stored.
+ *
+ * @retval GEIS_BAD_ARGUMENT    an invalid argument value was passed
+ * @retval GEIS_STATUS_SUCCESS  normal successful completion
+ */
+GEIS_API GeisStatus geis_configuration_get_value(GeisInstance geis_instance, 
+                                                 int          configuration_item,
+                                                 void         *value);
+
+/**
+ * Sets a feature configuration value.
+ *
+ * @param[in] geis_instance      An opaque pointer to a geis gesture subscription
+ *                               instance.
+ * @param[in] configuration_item Indicates which configuration item will be
+ *                               set.
+ * @param[in] value              A pointer to where the value to be set will be
+ *                               read.
+ *
+ * @retval GEIS_BAD_ARGUMENT    an invalid argument value was passed
+ * @retval GEIS_STATUS_SUCCESS  normal successful completion
+ */
+GEIS_API GeisStatus geis_configuration_set_value(GeisInstance geis_instance,
+                                                 int          configuration_item, 
+                                                 void         *value);
+
+/**
+ * Dispatches geis events until there are no further events available.
+ *
+ * @param[in] geis_instance     an opaque pointer to a geis gesture subscription
+ *                              instance
+ *
+ * This function is used to integrate geis even dispatch into the main event
+ * loop of an application or toolkit.
+ *
+ * @retval GEIS_BAD_ARGUMENT    an invalid GeisInstance was passed
+ * @retval GEIS_STATUS_SUCCESS  normal successful completion
+ */
+GEIS_API GeisStatus geis_event_dispatch(GeisInstance geis_instance);
+
+/* @} */
+
+/**
+ * @defgroup geis_v2_geis The Geis API Object
+ * @ingroup geis_v2
+ *
+ * @{
+ */
+
+/**
+ * @class Geis
+ * Represents an instance of the gestire recognition engine
+ */
+/** @cond typedef */
+typedef struct _Geis *Geis;
+/** @endcond */
+
+/**
+ * @name Standard Initialization Arguments
+ *
+ * @par
+ * These initialization arguments are defined by the GEIS v2 specification.
+ *
+ * @{
+ *
+ * @def GEIS_INIT_SERVICE_PROVIDER
  * Enables GEIS to provide a networked service.
- *
+ * This initialization argument takes no parameters.
+ *
+ * @def GEIS_INIT_TRACK_DEVICES
+ * Tells GEIS to send input device events.
+ * This initialization argument takes no parameters.
+ *
+ * @def GEIS_INIT_TRACK_GESTURE_CLASSES
+ * Tells GEIS to send gesture class events.
  * This initialization argument takes no parameters.
  */
+
 #define GEIS_INIT_SERVICE_PROVIDER     "org.libgeis.init.server"
-
-/**
- * Tells GEIS to send input device events.
- *
- * This initialization argument takes no parameters.
- */
 #define GEIS_INIT_TRACK_DEVICES        "org.libgeis.init.track-devices"
-
-/**
- * Tells GEIS to send gesture class events.
- *
- * This initialization argument takes no parameters.
- */
 #define GEIS_INIT_TRACK_GESTURE_CLASSES  "org.libgeis.init.track-gesture-classes"
 
 /* @} */
 
 /**
- * @defgroup geis_2_geis_init_vendor Vendor-defined Initialization Arguments
+ * @name Vendor-defined Initialization Arguments
  *
+ * @par
  * These initialization arguments are not a part of te GEIS specification and
  * may change.
  *
  * @{
+ *
+ * @def GEIS_INIT_UTOUCH_MOCK_ENGINE
+ *
+ * @def GEIS_INIT_UTOUCH_XCB
  */
 
 #define GEIS_INIT_UTOUCH_MOCK_ENGINE "com.canonical.utouch.mock.engine"
@@ -274,18 +418,27 @@
 /* @} */
 
 
-typedef struct _Geis *Geis;
-
 /**
  * Initializes an instance of the GEIS v2.0 API.
- *
- * @param[in]  name  A name for the API instance (used for diagnostics).
- * @param[in]  ...   A set of zero or more initialization arguments.
+ * @ingroup geis_v2_geis
+ * @memberof Geis
+ *
+ * @param[in]  init_arg_name  The name of an initializaer argument.
+ * @param[in]  ...            The remaining initializaer arguments.
+ *
+ * A NULL-terminated list of zero or more initialization arguments is passed to
+ * this function to create and initialize a connection to a gesture recognition
+ * engine.
+ *
+ * If no initialization arguments are passed, the parameter list consists of a
+ * single NULL argument.
  */
 GEIS_API Geis geis_new(GeisString init_arg_name, ...);
 
 /**
  * Cleans up an instance of the GEIS v2.0 API.
+ * @ingroup geis_v2_geis
+ * @memberof Geis
  *
  * @param[in] geis  An instance of the GEIS v2.0 API.
  *
@@ -297,7 +450,8 @@
 /* @} */
 
 /**
- * @defgroup geis_error Error Reporting
+ * @defgroup geis_v2_error Error Reporting
+ * @ingroup geis_v2
  * @{
  */
 
@@ -343,77 +497,22 @@
 /* @} */
 
 /**
- * @defgroup geis1_config Configuration and Control (GEIS v1.0)
- * @{
- */
-
-#define GEIS_CONFIG_UNIX_FD 10001
-
-/**
- * Indicates if a particular feaure is supported.
- *
- * @param[in] geis_instance     an opaque pointer to a geis gesture subscription
- *                              instance
- *
- * @retval GEIS_BAD_ARGUMENT    an invalid argument value was passed
- * @retval GEIS_STATUS_SUCCESS  normal successful completion
- */
-GEIS_API GeisStatus geis_configuration_supported(GeisInstance geis_instance,
-                                                 int          configuration_item);
-
-/**
- * Gets a feature configuration value.
- *
- * @param[in] geis_instance     an opaque pointer to a geis gesture subscription
- *                              instance
- *
- * @retval GEIS_BAD_ARGUMENT    an invalid argument value was passed
- * @retval GEIS_STATUS_SUCCESS  normal successful completion
- */
-GEIS_API GeisStatus geis_configuration_get_value(GeisInstance geis_instance, 
-                                                 int          configuration_item,
-                                                 void         *value);
-
-/**
- * Sets a feature configuration value.
- *
- * @param[in] geis_instance     an opaque pointer to a geis gesture subscription
- *                              instance
- *
- * @retval GEIS_BAD_ARGUMENT    an invalid argument value was passed
- * @retval GEIS_STATUS_SUCCESS  normal successful completion
- */
-GEIS_API GeisStatus geis_configuration_set_value(GeisInstance geis_instance,
-                                                 int          configuration_item, 
-                                                 void         *value);
-
-/**
- * Dispatches geis events until there are no further events available.
- *
- * @param[in] geis_instance     an opaque pointer to a geis gesture subscription
- *                              instance
- *
- * This function is used to integrate geis even dispatch into the main event
- * loop of an application or toolkit.
- *
- * @retval GEIS_BAD_ARGUMENT    an invalid GeisInstance was passed
- * @retval GEIS_STATUS_SUCCESS  normal successful completion
- */
-GEIS_API GeisStatus geis_event_dispatch(GeisInstance geis_instance);
-
-/* @} */
-
-/**
- * @defgroup geis2_config Configuration (GEIS v2.0)
- * @{
- */
-
-/**
- * @defgroup geis2_config_spec Required Configuration Items
- *
+ * @defgroup geis_v2_config Configuration
+ * @ingroup geis_v2
+ * @{
+ */
+
+/**
+ * @name Required Configuration Items
+ *
+ * @par
  * These configuration items are defined by the GEIS specification.
  *
  * @{
+ *
+ * @def GEIS_CONFIGURATION_FD
+ * Gets a Unix file descriptor that will signal the availablility of GEIS events
+ * for processing.
  */
 
 #define GEIS_CONFIGURATION_FD "org.libgeis.configuration.fd"
@@ -421,12 +520,15 @@
 /* @} */
 
 /**
- * @defgroup geis2_config_vendor Vendor-defined Configuration Items
+ * @name Vendor-defined Configuration Items
  *
+ * @par
  * These configuration items are not a part of the GEIS specification and may
  * change.
  *
  * @{
+ *
+ * @def GEIS_CONFIG_UTOUCH_MAX_EVENTS
  */
 
 #define GEIS_CONFIG_UTOUCH_MAX_EVENTS  "com.canonical.utouch.max_events"
@@ -454,9 +556,8 @@
 /**
  * Sets a feature configuration value.
  *
- * @param[in]  geis                 An opaque GEIS API object.
- * @param[in]  configuration_value  Selects the configuration value to return.
- * @param[in]  configuration_item_name  Selects the configuration value to return.
+ * @param[in] geis                     An opaque GEIS API object.
+ * @param[in] configuration_item_name  Selects the configuration value to return.
  * @param[in] configuration_item_value Points to a buffer to contain the output
  *                                     configuration value.  The actual type of
  *                                     this buffer depends on the
@@ -473,84 +574,8 @@
 /* @} */
 
 /**
- * @defgroup geis2_attrs Attributes
- *
- * Attributes are named values associated with various GEIS entities, including
- * input devices, gesture types, and gesture events.
- *
- * @{
- */
-typedef enum GeisAttrType
-{
-  GEIS_ATTR_TYPE_UNKNOWN,
-  GEIS_ATTR_TYPE_BOOLEAN,
-  GEIS_ATTR_TYPE_FLOAT,
-  GEIS_ATTR_TYPE_INTEGER,
-  GEIS_ATTR_TYPE_POINTER,
-  GEIS_ATTR_TYPE_STRING
-} GeisAttrType;
-
-/**
- * An opaque type that encapsulates a GEIS attribute.
- *
- * GeisAttr objects may not be created or destroyed by the application, they may
- * only have their data examined or extracted.
- */
-typedef struct _GeisAttr *GeisAttr;
-
-/**
- * Gets the name of an attribute.
- *
- * @param[in] attr  Identifies the attribute.
- */
-GEIS_API GeisString geis_attr_name(GeisAttr attr);
-
-/**
- * Gets the type of an attribute value.
- *
- * @param[in] attr  Identifies the attribute.
- */
-GEIS_API GeisAttrType geis_attr_type(GeisAttr attr);
-
-/**
- * Gets the value of an attribute as a GeisBoolean.
- *
- * @param[in] attr  Identifies the attribute.
- */
-GEIS_API GeisBoolean geis_attr_value_to_boolean(GeisAttr attr);
-
-/**
- * Gets the value of an attribute as a GeisFloat.
- *
- * @param[in] attr  Identifies the attribute.
- */
-GEIS_API GeisFloat geis_attr_value_to_float(GeisAttr attr);
-
-/**
- * Gets the value of an attribute as a GeisInteger.
- *
- * @param[in] attr  Identifies the attribute.
- */
-GEIS_API GeisInteger geis_attr_value_to_integer(GeisAttr attr);
-
-/**
- * Gets the value of an attribute as a GeisPointer.
- *
- * @param[in] attr  Identifies the attribute.
- */
-GEIS_API GeisPointer geis_attr_value_to_pointer(GeisAttr attr);
-
-/**
- * Gets the value of an attribute as a GeisString.
- *
- * @param[in] attr  Identifies the attribute.
- */
-GEIS_API GeisString geis_attr_value_to_string(GeisAttr attr);
-
-/* @} */
-
-/**
- * @defgroup geis_input Input Devices
+ * @defgroup geis_v1_input Input Devices
+ * @ingroup geis_v1
  * @{
  */
 
@@ -582,7 +607,7 @@
  *
  * @param[in] geis_instance   points to a geis gesture subscription
  *                            instance
- * @param[in] funcs           points to a GeisInputFuncs table
+ * @param[in] func            points to a GeisInputFuncs table
  * @param[in] cookie          an application specific value to be passed to
  *                            the callback
  *
@@ -601,22 +626,32 @@
 /* @} */
 
 /**
- * @defgroup geis1_subscription Gesture Subscription (GEIS v1.0)
+ * @defgroup geis_v1_subscription Gesture Subscription
+ * @ingroup geis_v1
  * @{
  */
 typedef unsigned int GeisGestureType;
 typedef unsigned int GeisGestureId;
 
+/** Selects ALL input devices. */
 #define GEIS_ALL_GESTURES ((GeisGestureType)0)
+
 #define GEIS_NO_GESTURE_ID ((GeisGestureId)0)
 
 /**
- * Gesture Attributes
+ * An individual gesture attribute.
+ *
+ * Gesture events are associated with a list of attributes, each of which is a
+ * (name, type, value) tuple.  These attribute reveal a little piece of
+ * information about a gesture.
  */
 typedef struct GeisGestureAttr
 {
+  /** The name of the gesture attribute. */
   GeisString name;
+  /** The data type of the gesture attribute. */
   GeisAttrType type;
+  /** The value of the attributes. */
   union
   {
     GeisBoolean boolean_val;
@@ -642,14 +677,23 @@
                                     GeisGestureAttr  *attrs);
 
 /**
- * A structure of callback functions.
+ * The set of callback functions invoked for various gesture-related events.
+ *
+ * An application must define callback functions to handle the various gesture
+ * events.  These callbacks are provided in a table passed to geis_subscribe for
+ * each window on which gesture events may occur.
  */
 typedef struct GeisGestureFuncs
 {
+  /** Invoked when a new gesture type has been defined. */
   GeisGestureCallback  added;
+  /** Invoked when a defined gesture type is no longer available. */
   GeisGestureCallback  removed;
+  /** Invoked when a new gesture starts. */
   GeisGestureCallback  start;
+  /** Invoked when a gesture has changed values. */
   GeisGestureCallback  update;
+  /** Invoked when a gesture finishes. */
   GeisGestureCallback  finish;
 } GeisGestureFuncs;
 
@@ -688,7 +732,79 @@
 /* @} */
 
 /**
- * @defgroup geis2_event_control Event Control (GEIS v2.0)
+ * @defgroup geis_v2_attrs Attributes
+ * @ingroup geis_v2
+ *
+ * Attributes are named values associated with various GEIS entities, including
+ * input devices, gesture types, and gesture events.
+ *
+ * @{
+ */
+
+/**
+ * An opaque type that encapsulates a GEIS attribute.
+ *
+ * GeisAttr objects may not be created or destroyed by the application, they may
+ * only have their data examined or extracted.
+ */
+/** @cond typedef */
+typedef struct _GeisAttr *GeisAttr;
+/** @endcond */
+
+/**
+ * Gets the name of an attribute.
+ *
+ * @param[in] attr  Identifies the attribute.
+ */
+GEIS_API GeisString geis_attr_name(GeisAttr attr);
+
+/**
+ * Gets the type of an attribute value.
+ *
+ * @param[in] attr  Identifies the attribute.
+ */
+GEIS_API GeisAttrType geis_attr_type(GeisAttr attr);
+
+/**
+ * Gets the value of an attribute as a GeisBoolean.
+ *
+ * @param[in] attr  Identifies the attribute.
+ */
+GEIS_API GeisBoolean geis_attr_value_to_boolean(GeisAttr attr);
+
+/**
+ * Gets the value of an attribute as a GeisFloat.
+ *
+ * @param[in] attr  Identifies the attribute.
+ */
+GEIS_API GeisFloat geis_attr_value_to_float(GeisAttr attr);
+
+/**
+ * Gets the value of an attribute as a GeisInteger.
+ *
+ * @param[in] attr  Identifies the attribute.
+ */
+GEIS_API GeisInteger geis_attr_value_to_integer(GeisAttr attr);
+
+/**
+ * Gets the value of an attribute as a GeisPointer.
+ *
+ * @param[in] attr  Identifies the attribute.
+ */
+GEIS_API GeisPointer geis_attr_value_to_pointer(GeisAttr attr);
+
+/**
+ * Gets the value of an attribute as a GeisString.
+ *
+ * @param[in] attr  Identifies the attribute.
+ */
+GEIS_API GeisString geis_attr_value_to_string(GeisAttr attr);
+
+/* @} */
+
+/**
+ * @defgroup geis_v2_event_control Event Control
+ * @ingroup geis_v2
  *
  * These functions are used to dispatch events generated from the various other
  * GEIS components.
@@ -718,48 +834,56 @@
 } GeisEventType;
 
 /**
- * Opaque pointer to a generic GEIS event.
+ * @class GeisEvent
+ * A generic GEIS event.
  *
  * Applications must determine the type of the actual event and convert the
  * opaque pointer to a concrete event pointer, if required.
  *
  * Events are created by the GEIS API but must be destroyed by the application.
  */
+/** @cond typedef */
 typedef struct _GeisEvent *GeisEvent;
+/** @endcond */
 
 /**
  * Destroys a GeisEvent.
+ * @memberof GeisEvent
  *
- * @param[in] geis The GeisEvent to destroy.
+ * @param[in] event The GeisEvent to destroy.
  */
 GEIS_API void geis_event_delete(GeisEvent event);
 
 /**
  * Gets the type of the event.
+ * @memberof GeisEvent
  *
- * @param[in] geis The GeisEvent to destroy.
+ * @param[in] event The GeisEvent to destroy.
  */
 GEIS_API GeisEventType geis_event_type(GeisEvent event);
 
 /**
  * Gets the number of attributes in the event.
+ * @memberof GeisEvent
  *
- * @param[in] geis The GeisEvent.
+ * @param[in] event The GeisEvent.
  */
 GEIS_API GeisSize geis_event_attr_count(GeisEvent event);
 
 /**
  * Gets an indicated attribute from the event.
+ * @memberof GeisEvent
  *
- * @param[in] geis  The GeisEvent.
- * @param[in] index Indicates the attribute to retrieve.
+ * @param[in] event  The GeisEvent.
+ * @param[in] index  Indicates the attribute to retrieve.
  */
 GEIS_API GeisAttr geis_event_attr(GeisEvent event, GeisSize index);
 
 /**
  * Gets a named attribute from the event.
+ * @memberof GeisEvent
  *
- * @param[in] geis      The GeisEvent.
+ * @param[in] event     The GeisEvent.
  * @param[in] attr_name The name of the attribute to retrieve.
  */
 GEIS_API GeisAttr geis_event_attr_by_name(GeisEvent event, GeisString attr_name);
@@ -804,7 +928,6 @@
  * Pumps the GEIS event loop.
  *
  * @param[in]  geis  The GEIS API instance.
- * @param[out] event An opeaque event object.
  *
  * Processes input events until there are no more input events to process and
  * generates zero or more gesture events, reporting them via the user-supplied
@@ -850,12 +973,31 @@
 /* @} */
 
 /**
- * @defgroup geis2_device Gesture Input Devices (GEIS v2.0)
- * @{
+ * @defgroup geis_v2_device Input Devices
+ * @ingroup geis_v2
+ * @{
+ */
+
+/**
+ * @name Device Event Attributes
+ * @{
+ *
+ * @def GEIS_EVENT_ATTRIBUTE_DEVICE
+ * The event attribute containing a pointer to a GeisDevice.
+ *
+ * The GEIS_EVENT_DEVICE_AVAILABLE and GEIS_EVENT_DEVICE_UNAVAILABLE events
+ * should have a GEIS_ATTR_TYPE_POINTER attribute with this name.  It
+ * should contain a pointer to a GeisDevice describing the device made available
+ * or unavailable.
  */
 #define GEIS_EVENT_ATTRIBUTE_DEVICE             "device"
 
+/* @} */
+
 /**
+ * @name Device Attributes
+ * @{
+ *
  * @def GEIS_DEVICE_ATTRIBUTE_NAME
  * The name of the input device.  Not guaranteed unique.
  *
@@ -864,15 +1006,23 @@
  * instance.
  *
  * @def GEIS_DEVICE_ATTRIBUTE_TOUCHES
- * The simultaneous number of touches the device claims to be able to detect if
- * it is a multi-touch device.  A value of zero indicates the maximum number of
- * touches can not be determined.
+ * The maximum number of touches a device is capable of reporting.
+ * This integer is the number if simultaneous touches the device claims to be
+ * able to detect if it is a multi-touch device.  A value of zero indicates the
+ * maximum number of touches can not be determined.
  *
  * @def GEIS_DEVICE_ATTRIBUTE_DIRECT_TOUCH
- * Indicates if this is a direct touch device (eg. touchscreen).
+ * Indicates the device is a direct touch device.
+ * The present of this boolean attribute with a value of GEIS_TRUE indicates the
+ * device is a direct touch multi-touch device (for example, a touchscreen),
+ * otherwise it is an indirect touch device (such as a touchpad) or not a touch
+ * device at all.
  *
  * @def GEIS_DEVICE_ATTRIBUTE_INDEPENDENT_TOUCH
- * Indicates if this is an independent touch device (eg. Apple MagicMouse).
+ * Indicates the device is an independent touch device.
+ * The presence of this boolean attribute with a value of GEIS_TRUE indicates
+ * the device is an independent touch device (for example, an Apple MagicMouse).
+ * Other multi-touch devices should report GEIS_FALSE.
  */
 #define GEIS_DEVICE_ATTRIBUTE_NAME              "device name"
 #define GEIS_DEVICE_ATTRIBUTE_ID                "device id"
@@ -880,14 +1030,17 @@
 #define GEIS_DEVICE_ATTRIBUTE_DIRECT_TOUCH      "direct touch"
 #define GEIS_DEVICE_ATTRIBUTE_INDEPENDENT_TOUCH "independent touch"
 
+/* @} */
 
 /**
  * @class GeisDevice
- * An opaque pointer type representing a gesture-capable input device.
+ * A gesture-capable input device.
  *
  * GeisDevice objects are created by the GEIS API and are reference counted.
  */
+/** @cond typedef */
 typedef struct _GeisDevice *GeisDevice;
+/** @endcond */
 
 GEIS_API void geis_register_device_callback(Geis               geis,
                                             GeisEventCallback  event_callback,
@@ -895,7 +1048,7 @@
 
 /**
  * Adds a reference count to a device.
- * @public @memberof GeisDevice
+ * @memberof GeisDevice
  *
  * @param[in] device The device.
  *
@@ -907,7 +1060,7 @@
 
 /**
  * Removes a reference count from a device.
- * @public @memberof GeisDevice
+ * @memberof GeisDevice
  *
  * @param[in] device The device.
  *
@@ -948,29 +1101,60 @@
  * @memberof GeisDevice
  *
  * @param[in] device The device.
+ * @param[in] index  Indicates which attr to retrieve.
  */
 GEIS_API GeisAttr geis_device_attr(GeisDevice device, GeisSize index);
 
 /* @} */
 
 /**
- * @defgroup geis2_class Gesture Classes (GEIS v2.0)
+ * @defgroup geis_v2_class Gesture Classes
+ * @ingroup geis_v2
  * @{
  */
 
 /**
- * An opaque pointer type representing a gesture-capable input device.
+ * @class GeisGestureClass
+ * A defined gesture classifier.
  *
- * GeisDevice objects are created by the GEIS API and are reference counted.  An
- * application needs to increment and decrement the reference count of a gesture
- * class object to control its persistence.
+ * GeisGestureClass objects are created by the GEIS API and are reference
+ * counted.  An application needs to increment and decrement the reference
+ * count of a gesture class object to control its persistence.
  */
+/** @cond typedef */
 typedef struct _GeisGestureClass *GeisGestureClass;
-
+/** @endcond */
+
+/**
+ * @name Gesture Class Event Attributes
+ * @{
+ *
+ * @def GEIS_EVENT_ATTRIBUTE_CLASS
+ * The event attribute containing a pointer to a GeisGestureClass. 
+ *
+ * The GEIS_EVENT_CLASS_AVAILABLE and GEIS_EVENT_CLASS_UNAVAILABLE events
+ * should have a GEIS_ATTR_TYPE_POINTER attribute with this name.  It
+ * should contain a pointer to a GeisGestureClass describing the gesture class
+ * made available or unavailable.
+ */
+#define GEIS_EVENT_ATTRIBUTE_CLASS  "gesture class"
+
+/* @} */
+
+/**
+ * @name Gesture Class Attributes
+ * @{
+ *
+ * @def GEIS_CLASS_ATTRIBUTE_NAME
+ * The name of the gesture class. 
+ *
+ * @def GEIS_CLASS_ATTRIBUTE_ID
+ * The unique integer ID of the gesture class.
+ */
 #define GEIS_CLASS_ATTRIBUTE_NAME   "class name"
 #define GEIS_CLASS_ATTRIBUTE_ID     "class id"
 
-#define GEIS_EVENT_ATTRIBUTE_CLASS  "gesture class"
+/* @} */
 
 /**
  * Registers a callback to receive gesture class change notifications.
@@ -997,6 +1181,7 @@
 
 /**
  * Increments the reference count of a gesture class object.
+ * @memberof GeisGestureClass
  *
  * @param[in] gesture_class  The gesture class object.
  */
@@ -1004,6 +1189,7 @@
 
 /**
  * Decrements the reference count of a gesture class object.
+ * @memberof GeisGestureClass
  *
  * @param[in] gesture_class  The gesture class object.
  *
@@ -1014,6 +1200,7 @@
 
 /**
  * Gets the name of the gesture class.
+ * @memberof GeisGestureClass
  *
  * @param[in] gesture_class  The gesture class object.
  */
@@ -1021,6 +1208,7 @@
 
 /**
  * Gets the numeric identifier of the gesture class.
+ * @memberof GeisGestureClass
  *
  * @param[in] gesture_class  The gesture class object.
  */
@@ -1028,6 +1216,7 @@
 
 /**
  * Gets the number of attributes of the gesture class.
+ * @memberof GeisGestureClass
  *
  * @param[in] gesture_class  The gesture class object.
  */
@@ -1035,6 +1224,7 @@
 
 /**
  * Gets the indicated attribute of teh gesture class.
+ * @memberof GeisGestureClass
  *
  * @param[in] gesture_class  The gesture class object.
  * @param[in] index          The index of the attribute to retrieve.
@@ -1045,32 +1235,66 @@
 /* @} */
 
 /**
- * @defgroup geis2_region Gesture Regions (GEIS v2.0)
+ * @defgroup geis_v2_region Gesture Regions
+ * @ingroup geis_v2
  * @{
  */
 
+/**
+ * @class GeisRegion
+ * Defines a region over which gestures may take place.
+ */
+/** @cond typedef */
 typedef struct _GeisRegion *GeisRegion;
-
-/**
- * @defgroup geis2_region_init_args Gesture Region Initialization Arguments
- *
+/** @endcond */
+
+/**
+ * @name Region Attributes
+ *
+ * @par
+ * These attributes can be used to construct filter terms to restrict a
+ * gesture subscription to a particular region.
+ *
+ * @{
+ *
+ * @def GEIS_REGION_ATTRIBUTE_WINDOWID
+ * The X11 windowid in which a gesture occurred. Used for filter matching.
+ */
+#define GEIS_REGION_ATTRIBUTE_WINDOWID          "windowid"
+
+/* @} */
+
+/**
+ * @name Region Initialization Arguments
+ *
+ * @par
  * Gesture regions are created to describe a particular display/feedback region.
  * The type of the region can not be changed after creation (just create a new
  * region for that).  The types of regions are platform specific and each type
  * may require addition arguments.
  *
+ * @par
  * The following region initialization argument names are required by the
  * GEIS v2.0 specification.
  *
  * @{
+ *
+ * @def GEIS_REGION_X11_ROOT
+ * Selects the X11 root window as a region.
+ *
+ * @def GEIS_REGION_X11_WINDOWID
+ * Selects an X11 window as a region.
+ * Requires the window_id as an argument.
  */
 #define GEIS_REGION_X11_ROOT       "org.libgeis.region.x11.root"
+
 #define GEIS_REGION_X11_WINDOWID   "org.libgeis.region.x11.windowid"
 
 /* @} */
 
 /**
  * Creates a new GEIS v2.0 region.
+ * @memberof GeisRegion
  *
  * @param[in] geis           The GEIS API instance.
  * @param[in] name           A name.  Used for diagnostics.
@@ -1086,6 +1310,7 @@
 
 /**
  * Destroys a GEIS v2.0 region.
+ * @memberof GeisRegion
  *
  * @param[in] region  The region.
  */
@@ -1093,6 +1318,7 @@
 
 /**
  * Gets the name of a GEIS v2.0 region.
+ * @memberof GeisRegion
  *
  * @param[in] region  The region.
  *
@@ -1103,32 +1329,51 @@
 /* @} */
 
 /**
- * @defgroup geis2_filter Gesture Filter (GEIS v2.0)
+ * @defgroup geis_v2_filter Gesture Filter
+ * @ingroup geis_v2
  * @{
  */
 
+/**
+ * @class GeisFilter
+ * Selects a subset of possible gestures in a subscription.
+ *
+ * A GeisFilter is a collection of filter terms, each of which defines a
+ * criterion for selection of gestures returned on a subscription.
+ *
+ * All filter terms are effectively ANDed together in a filter.
+ **/
+/** @cond typedef */
 typedef struct _GeisFilter *GeisFilter;
+/** @endcond */
 
+/**
+ * Indicates the type of filter.
+ */
 typedef enum _GeisFilterFacility
 {
-  GEIS_FILTER_DEVICE   = 1000,
-  GEIS_FILTER_CLASS    = 2000,
-  GEIS_FILTER_REGION   = 3000
+  GEIS_FILTER_DEVICE   = 1000,  /**< Filters on device attributes. */
+  GEIS_FILTER_CLASS    = 2000,  /**< Filters on gesture attributes. */
+  GEIS_FILTER_REGION   = 3000   /**< Filters on region attributes. */
 } GeisFilterFacility;
 
+/**
+ * Indicates the type of filter operation.
+ */
 typedef enum _GeisFilterOperation
 {
-  GEIS_FILTER_OP_EQ,
-  GEIS_FILTER_OP_NE,
-  GEIS_FILTER_OP_GT,
-  GEIS_FILTER_OP_GE,
-  GEIS_FILTER_OP_LT,
-  GEIS_FILTER_OP_LE
+  GEIS_FILTER_OP_EQ,      /**< Compares for equality. */
+  GEIS_FILTER_OP_NE,      /**< Compares for inequality */
+  GEIS_FILTER_OP_GT,      /**< Compares for greater-than. */
+  GEIS_FILTER_OP_GE,      /**< Compares for greater-than-or-equal. */
+  GEIS_FILTER_OP_LT,      /**< Compares for less-than. */
+  GEIS_FILTER_OP_LE       /**< Compares for less-tha-or-equal. */
 } GeisFilterOperation;
 
 
 /**
  * Creates a new, empty filter.
+ * @memberof GeisFilter
  *
  * @param[in] geis  The GEIS API instance.
  * @param[in] name  A name.
@@ -1139,16 +1384,20 @@
 
 /**
  * Creates a new filter by copying an existing filter.
+ * @memberof GeisFilter
  *
  * @param[in] original  An existing geisFilter instance.
  * @param[in] name      A name.
  *
+ * The original filter remains unchanged.
+ *
  * @returns a GeisFilter object or NULL on failure.
  */
 GEIS_API GeisFilter geis_filter_clone(GeisFilter original, GeisString name);
 
 /**
- * Destroys a GEIS v2.0 filter object.
+ * Destroys a GeisFilter.
+ * @memberof GeisFilter
  *
  * @param[in] filter  The filter.
  */
@@ -1156,6 +1405,7 @@
 
 /**
  * Gets the name given to the filter when it was created.
+ * @memberof GeisFilter
  *
  * @param[in] filter  The filter.
  */
@@ -1163,6 +1413,7 @@
 
 /**
  * Adds a term to a filter.
+ * @memberof GeisFilter
  *
  * @param[in] filter   The filter.
  * @param[in] facility The term facility.
@@ -1180,16 +1431,38 @@
 /* @} */
 
 /**
- * @defgroup geis2_subscription Gesture Subscription (GEIS v2.0)
+ * @defgroup geis_v2_subscription Gesture Subscription
+ * @ingroup geis_v2
  * @{
  */
 
+/**
+ * @class GeisSubscription
+ * A gesture recognition subscription.
+ */
+/** @cond typedef */
 typedef struct _GeisSubscription *GeisSubscription;
+/** @endcond */
 
 /**
- * Flags to refine the behaviour of the gesture subscription.
+ * @enum GeisSubscriptionFlags
+ *
+ * These flags are used when creating a new subscription and affect the nature
+ * of the gestures recognized by the subscription.  They may ORed together.
+ *
+ * @var GeisSubscriptionFlags::GEIS_SUBSCRIPTION_NONE
+ * No special subscription processing:  this is the default.
+ *
+ * @var GeisSubscriptionFlags::GEIS_SUBSCRIPTION_GRAB
+ * The subscription will "grab" all filtered gestures from subwindows.
+ *
+ * @var GeisSubscriptionFlags::GEIS_SUBSCRIPTION_CONT
+ * The gesture engine will return <em>gesture continuations</em>, in which the
+ * class of a recognized gestire may change over the lifetime of the gesture.
+ * If this flag is not set, a new gesture will be identified for each change in
+ * gesture class.
  */
-typedef enum _GeisSubscriptionFlags
+typedef enum GeisSubscriptionFlags
 {
   GEIS_SUBSCRIPTION_NONE = 0x0000,
   GEIS_SUBSCRIPTION_GRAB = 0x0001,
@@ -1198,6 +1471,7 @@
 
 /**
  * Creates a new subscription.
+ * @memberof GeisSubscription
  *
  * @param[in] geis  The GEIS API instance.
  * @param[in] name  A name.
@@ -1214,6 +1488,7 @@
 
 /**
  * Destroys a GEIS v2.0 subscription object.
+ * @memberof GeisSubscription
  *
  * @param[in] subscription  The subscription.
  */
@@ -1221,6 +1496,7 @@
 
 /**
  * Activates a subscription.
+ * @memberof GeisSubscription
  *
  * @param[in] subscription  The subscription.
  *
@@ -1231,6 +1507,7 @@
 
 /**
  * Deactivates a subscription.
+ * @memberof GeisSubscription
  *
  * @param[in] subscription  The subscription.
  *
@@ -1241,6 +1518,7 @@
 
 /**
  * Gets the name given to a subscription when it was created.
+ * @memberof GeisSubscription
  *
  * @param[in] subscription  The subscription.
  */
@@ -1248,6 +1526,7 @@
 
 /**
  * Gets the ID assigned to a subscription when it was created.
+ * @memberof GeisSubscription
  *
  * @param[in] subscription  The subscription.
  */
@@ -1255,6 +1534,7 @@
 
 /**
  * Adds a filter to a subscription.
+ * @memberof GeisSubscription
  *
  * @param[in] subscription  The subscription.
  * @param[in] filter        The filter to be added to the subscription.
@@ -1271,6 +1551,7 @@
 
 /**
  * Gets an named filter from a subscription.
+ * @memberof GeisSubscription
  *
  * @param[in] sub  The subscription.
  * @param[in] name Names the filter to retrieve.
@@ -1283,6 +1564,7 @@
 
 /**
  * Removes a filter from a subscription.
+ * @memberof GeisSubscription
  *
  * @param[in] subscription  The subscription.
  * @param[in] filter        The filter to be removed from the subscription.
@@ -1293,22 +1575,93 @@
 /* @} */
 
 /**
- * @defgroup geis2_gesture Gesture Frames (GEIS v2.0)
+ * @defgroup geis_v2_gesture Gesture Frames
+ * @ingroup geis_v2
+ * Gesture state information.
+ *
+ * Gesture frames, and their associated groups and touches, convey information
+ * about the current state of recognized gestures.
+ *
  * @{
  */
 
+/**
+ * @class GeisGroup
+ * A collection of gesture frames.
+ *
+ * @class GeisGroupSet
+ * A collection of GeisGroups.
+ *
+ * @class GeisTouch
+ * An instance of a touch.
+ *
+ * @class GeisTouchId
+ * Relates a touch in a frame to a touch object in a set.
+ *
+ * @class GeisTouchSet
+ * A collection of GeisTouch
+ *
+ * @class GeisFrame
+ * A collection of information describing the state of a gesture.
+ */
+/** @cond typedef */
 typedef struct _GeisGroup    *GeisGroup;
 typedef struct _GeisGroupSet *GeisGroupSet;
 typedef GeisSize              GeisTouchId;
 typedef struct _GeisTouch    *GeisTouch;
 typedef struct _GeisTouchSet *GeisTouchSet;
 typedef struct _GeisFrame    *GeisFrame;
+/** @endcond */
 
+/**
+ * @name Gesture Frame Event Attributes
+ *
+ * @par
+ * A gesture event (GEIS_EVENT_GESTURE_BEGIN, GEIS_EVENT_GESTURE_UPDATE,
+ * GEIS_EVENT_GESTURE_END) should have two GEIS_ATTR_TYPE_POINTER attributes,
+ * one containing a GeisGroupSet and one containing a GeisTouchSet.
+ *
+ * @{
+ *
+ * @def GEIS_EVENT_ATTRIBUTE_GROUPSET
+ * The event attribute containing a pointer to a GeisGroupSet.
+ *
+ * @def GEIS_EVENT_ATTRIBUTE_TOUCHSET
+ * The event attribute containing a pointer to a GeisTouchSet.
+ */
 #define GEIS_EVENT_ATTRIBUTE_GROUPSET  "group set"
 #define GEIS_EVENT_ATTRIBUTE_TOUCHSET  "touch set"
 
+/* @} */
+
+/**
+ * @name Touch Attributes
+ *
+ * @par
+ * Each touch has zero or more attributes associated with it. Differing hardware
+ * is capable of reporting differing sets of touch attributes, so there is no
+ * guarantee that any or all of the defined touch attributes will bre present.
+ *
+ * @{
+ *
+ * @def GEIS_TOUCH_ATTRIBUTE_ID
+ * Identifies the touch. 
+ *
+ * @def GEIS_TOUCH_ATTRIBUTE_X
+ * The X coordinate of the touch.
+ *
+ * @def GEIS_TOUCH_ATTRIBUTE_Y
+ * The Y coordinate of the touch.
+ */
+#define GEIS_TOUCH_ATTRIBUTE_ID                 "touch id"
+#define GEIS_TOUCH_ATTRIBUTE_X                  "touch x"
+#define GEIS_TOUCH_ATTRIBUTE_Y                  "touch y"
+
+/* @} */
+
 /**
  * Gets the number of gesture groups in a groupset.
+ * @memberof GeisGroupSet
  *
  * @param[in] groupset The groupset.
  */
@@ -1316,6 +1669,7 @@
 
 /**
  * Gets an indicated gesture group from a groupset.
+ * @memberof GeisGroupSet
  *
  * @param[in] groupset The groupset.
  * @param[in] index    Indicates which gesture group to retrieve.
@@ -1324,6 +1678,7 @@
 
 /**
  * Gets the identifier of a gesture group.
+ * @memberof GeisGroup
  *
  * @param[in] group The gesture group.
  */
@@ -1331,6 +1686,7 @@
 
 /**
  * Gets the number of gesture frames in a gesture group.
+ * @memberof GeisGroup
  *
  * @param[in] group The gesture group.
  */
@@ -1338,6 +1694,7 @@
 
 /**
  * Gets an indicated gesture frame from a gesture group.
+ * @memberof GeisGroup
  *
  * @param[in] group The gesture group.
  * @param[in] index Indicates which gesture frame to retrieve.
@@ -1346,6 +1703,7 @@
 
 /**
  * Marks a gesture group as rejected.
+ * @memberof GeisGroup
  *
  * @param[in] group The gesture group to reject.
  */
@@ -1353,6 +1711,7 @@
 
 /**
  * Gets the number of touches in a touchset.
+ * @memberof GeisTouchSet
  *
  * @param[in] touchset  The touchset,
  */
@@ -1360,6 +1719,7 @@
 
 /**
  * Gets an indicated touch from a touchset.
+ * @memberof GeisTouchSet
  *
  * @param[in] touchset  The touchset.
  * @param[in] index     Indicates which touch to retrieve.
@@ -1368,6 +1728,7 @@
 
 /**
  * Gets an identified touch from a touchset.
+ * @memberof GeisTouchSet
  *
  * @param[in] touchset  The touchset.
  * @param[in] touchid   Identifies a touch.
@@ -1379,6 +1740,7 @@
 
 /**
  * Gets the identifier of a touch.
+ * @memberof GeisTouch
  *
  * @param[in] touch  The touch.
  */
@@ -1386,6 +1748,7 @@
 
 /**
  * Gets the number of attrs associated with a touch.
+ * @memberof GeisTouch
  *
  * @param[in] touch  The touch.
  */
@@ -1393,6 +1756,7 @@
 
 /**
  * Gets an indicated attr from a touch.
+ * @memberof GeisTouch
  *
  * @param[in] touch  The touch.
  * @param[in] index  Indicates which attr to retrieve.
@@ -1401,6 +1765,7 @@
 
 /**
  * Gets a named attr from a touch.
+ * @memberof GeisTouch
  *
  * @param[in] touch  The touch.
  * @param[in] name   Names the attr to retrieve.
@@ -1411,6 +1776,7 @@
 
 /**
  * Gets the identifier of a gesture frame.
+ * @memberof GeisFrame
  *
  * @param[in] frame  the gesture frame.
  */
@@ -1418,6 +1784,7 @@
 
 /**
  * Indicates if a gesture frame belongs to a gesture class.
+ * @memberof GeisFrame
  *
  * @param[in] frame         The gesture frame.
  * @param[in] gesture_class The gesture class.
@@ -1430,6 +1797,7 @@
 
 /**
  * Gets the number of attrs associated with a gesture frame.
+ * @memberof GeisFrame
  *
  * @param[in] frame  The gesture frame.
  */
@@ -1437,6 +1805,7 @@
 
 /**
  * Gets an indicated attr from a gesture frame.
+ * @memberof GeisFrame
  *
  * @param[in] frame  The gesture frame.
  * @param[in] index  Indicates which attr to retrieve.
@@ -1445,6 +1814,7 @@
 
 /**
  * Gets a named attr from a gesture frame.
+ * @memberof GeisFrame
  *
  * @param[in] frame  The gesture frame.
  * @param[in] name   Names the attr to retrieve.
@@ -1455,6 +1825,7 @@
 
 /**
  * Gets the current transform matrix of a gesture.
+ * @memberof GeisFrame
  *
  * @param[in] frame  The gesture frame.
  */
@@ -1462,6 +1833,7 @@
 
 /**
  * Gets the number of touches making up a gesture for the frame.
+ * @memberof GeisFrame
  *
  * @param[in] frame  The gesture frame.
  */
@@ -1469,6 +1841,7 @@
 
 /**
  * Gets the ID of the indicated touch within the gesture frame.
+ * @memberof GeisFrame
  *
  * @param[in] frame  The gesture frame.
  * @param[in] index  Indicates which touch ID to retrieve.
@@ -1477,10 +1850,11 @@
 
 /**
  * Marks a gesture as rejected.
+ * @memberof GeisFrame
  *
  * @param[in] gesture_id  Identifies the gesture.
  */
-GEIS_API void geis_gesture_reject(GeisGestureId gestureid);
+GEIS_API void geis_gesture_reject(GeisGestureId gesture_id);
 
 /* @} */