[gtk+/touch-for-3.4] Improve touch event docs

[Matthias Clasen <matthiasc src gnome org>]

commit bab5b76702e9b0d43309a29f1da203de87cd7c52
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Feb 29 16:47:04 2012 -0500

    Improve touch event docs

 gdk/gdkevents.h |   51 ++++++++++++++++++++++++++-------------------------
 gdk/gdktypes.h  |    8 ++++----
 2 files changed, 30 insertions(+), 29 deletions(-)
---
diff --git a/gdk/gdkevents.h b/gdk/gdkevents.h
index 644e5c2..5db2ecc 100644
--- a/gdk/gdkevents.h
+++ b/gdk/gdkevents.h
@@ -266,13 +266,13 @@ typedef GdkFilterReturn (*GdkFilterFunc) (GdkXEvent *xevent,
  *   was added in 2.8.
  * @GDK_DAMAGE: the content of the window has been changed. This event type
  *   was added in 2.14.
- * @GDK_TOUCH_UPDATE: A touch device has been updated. This event type
+ * @GDK_TOUCH_BEGIN: A new touch event sequence has just started. This event
+ *   type was added in 3.4.
+ * @GDK_TOUCH_UPDATE: A touch event sequence has been updated. This event type
  *   was added in 3.4.
- * @GDK_TOUCH_BEGIN: A new touch stream has just started. This event type
+ * @GDK_TOUCH_END: A touch event sequence has finished. This event type
  *   was added in 3.4.
- * @GDK_TOUCH_END: A touch stream has finished. This event type
- *   was added in 3.4.
- * @GDK_TOUCH_CANCEL: A touch stream has been canceled. This event type
+ * @GDK_TOUCH_CANCEL: A touch event sequence has been canceled. This event type
  *   was added in 3.4.
  * @GDK_EVENT_LAST: marks the end of the GdkEventType enumeration. Added in 2.18
  *
@@ -622,8 +622,7 @@ struct _GdkEventMotion
  *
  * Used for button press and button release events. The
  * @type field will be one of %GDK_BUTTON_PRESS,
- * %GDK_2BUTTON_PRESS, %GDK_3BUTTON_PRESS, %GDK_BUTTON_RELEASE,
- * %GDK_TOUCH_PRESS and %GDK_TOUCH_RELEASE.
+ * %GDK_2BUTTON_PRESS, %GDK_3BUTTON_PRESS or %GDK_BUTTON_RELEASE,
  *
  * Double and triple-clicks result in a sequence of events being received.
  * For double-clicks the order of events will be:
@@ -655,11 +654,6 @@ struct _GdkEventMotion
  * For a double click to occur, the second button press must occur within
  * 1/4 of a second of the first. For a triple click to occur, the third
  * button press must also occur within 1/2 second of the first button press.
- *
- * If the event has a type of %GDK_TOUCH_PRESS or %GDK_TOUCH_RELEASE,
- * this event will pertain to a sequence identified by
- * gdk_event_get_touch_sequence(). With multitouch devices, there may be
- * several ongoing sequences.
  */
 struct _GdkEventButton
 {
@@ -679,30 +673,37 @@ struct _GdkEventButton
 /**
  * GdkEventTouch:
  * @type: the type of the event (%GDK_TOUCH_BEGIN, %GDK_TOUCH_UPDATE,
- *   %GDK_TOUCH_END, %GDK_TOUCH_CANCEL).
- * @window: the window which received the event.
+ *   %GDK_TOUCH_END, %GDK_TOUCH_CANCEL)
+ * @window: the window which received the event
  * @send_event: %TRUE if the event was sent explicitly (e.g. using
- *   <function>XSendEvent</function>).
+ *   <function>XSendEvent</function>)
  * @time: the time of the event in milliseconds.
- * @x: the x coordinate of the pointer relative to the window.
- * @y: the y coordinate of the pointer relative to the window.
+ * @x: the x coordinate of the pointer relative to the window
+ * @y: the y coordinate of the pointer relative to the window
  * @axes: @x, @y translated to the axes of @device, or %NULL if @device is
- *   the mouse.
+ *   the mouse
  * @state: (type GdkModifierType): a bit-mask representing the state of
  *   the modifier keys (e.g. Control, Shift and Alt) and the pointer
- *   buttons. See #GdkModifierType.
- * @sequence: the touch sequence that the event belongs to
+ *   buttons. See #GdkModifierType
+ * @sequence: the event sequence that the event belongs to
  * @emulating_pointer: whether the event should be used for emulating
- *   pointer events
- * @device: the device where the event originated.
+ *   pointer event
+ * @device: the device where the event originated
  * @x_root: the x coordinate of the pointer relative to the root of the
- *   screen.
+ *   screen
  * @y_root: the y coordinate of the pointer relative to the root of the
- *   screen.
+ *   screen
  *
- * Used for touch event.
+ * Used for touch events.
  * @type field will be one of %GDK_TOUCH_BEGIN, %GDK_TOUCH_UPDATE,
  * %GDK_TOUCH_END or %GDK_TOUCH_CANCEL.
+ *
+ * Touch events are grouped into sequences by means of the @sequence
+ * field, which can also be obtained with gdk_event_get_event_sequence().
+ * Each sequence begins with a %GDK_TOUCH_BEGIN event, followed by
+ * any number of %GDK_TOUCH_UPDATE events, and ends with a %GDK_TOUCH_END
+ * (or %GDK_TOUCH_CANCEL) event. With multitouch devices, there may be
+ * several active sequences at the same time.
  */
 struct _GdkEventTouch
 {
diff --git a/gdk/gdktypes.h b/gdk/gdktypes.h
index ee0cd95..4bee311 100644
--- a/gdk/gdktypes.h
+++ b/gdk/gdktypes.h
@@ -369,10 +369,10 @@ typedef enum
  *
  * If %GDK_TOUCH_MASK is enabled, the window will receive touch events
  * from touch-enabled devices. Those will come as sequences of #GdkEventTouch
- * with type %GDK_TOUCH_UPDATE, enclosed by 2 #GdkEventTouch events with
- * type %GDK_TOUCH_BEGIN / %GDK_TOUCH_END. gdk_event_get_touch_id() will
- * return the touch ID on those events, so different sequences may be
- * distinguished.
+ * with type %GDK_TOUCH_UPDATE, enclosed by two events with
+ * type %GDK_TOUCH_BEGIN and %GDK_TOUCH_END (or %GDK_TOUCH_CANCEL).
+ * gdk_event_get_event_sequence() returns the event sequence for these
+ * events, so different sequences may be distinguished.
  */
 typedef enum
 {