[gtk+/multitouch: 21/23] gtk: Document helper GtkWidget gestures API

[Carlos Garnacho <carlosg src gnome org>]

commit d682dafa339096ee3895688b6341b5f752792ed7
Author: Carlos Garnacho <carlosg gnome org>
Date:   Tue Oct 25 18:12:29 2011 +0200

    gtk: Document helper GtkWidget gestures API

 docs/reference/gtk/gtk3-sections.txt |    4 ++++
 gtk/gtkwidget.c                      |   23 +++++++++++++++++++++++
 gtk/gtkwidget.h                      |    6 +++---
 3 files changed, 30 insertions(+), 3 deletions(-)
---
diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt
index c005e54..9f6ce41 100644
--- a/docs/reference/gtk/gtk3-sections.txt
+++ b/docs/reference/gtk/gtk3-sections.txt
@@ -5296,6 +5296,10 @@ gtk_widget_set_vexpand_set
 gtk_widget_queue_compute_expand
 gtk_widget_compute_expand
 
+<SUBSECTION Gestures>
+gtk_widget_enable_gesture
+gtk_widget_disable_gesture
+
 <SUBSECTION Standard>
 GTK_WIDGET
 GTK_IS_WIDGET
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 8eae99f..056c9e5 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -3016,6 +3016,15 @@ gtk_widget_class_init (GtkWidgetClass *klass)
 		  _gtk_marshal_BOOLEAN__UINT,
                   G_TYPE_BOOLEAN, 1, G_TYPE_UINT);
 
+  /**
+   * GtkWidget::gesture:
+   * @widget: the object which received the signal
+   * @gesture_id: gesture recognized
+   *
+   * This signal is emitted whenever a device with source
+   * #GDK_SOURCE_TOUCHSCREEN finishes a gesture that resembles
+   * one of those added through gtk_widget_enable_gesture().
+   */
   widget_signals[GESTURE] =
     g_signal_new (I_("gesture"),
                   G_TYPE_FROM_CLASS (klass),
@@ -14659,6 +14668,13 @@ _gtk_widget_gesture_finish (GtkWidget *widget)
     g_signal_emit (widget, widget_signals[GESTURE], 0, gesture);
 }
 
+/**
+ * gtk_widget_enable_gesture:
+ * @widget: a #GtkWidget
+ * @gesture_id: gesture ID to handle
+ *
+ * Enables @gesture_id to be recognized in @widget.
+ **/
 void
 gtk_widget_enable_gesture (GtkWidget *widget,
                            guint      gesture_id)
@@ -14687,6 +14703,13 @@ gtk_widget_enable_gesture (GtkWidget *widget,
   g_array_append_val (priv->gestures, gesture_id);
 }
 
+/**
+ * gtk_widget_disable_gesture:
+ * @widget: a #GtkWidget
+ * @gesture_id: Gesture ID to stop handling
+ *
+ * Disables a gesture previously added through gtk_widget_enable_gesture()
+ **/
 void
 gtk_widget_disable_gesture (GtkWidget *widget,
                             guint      gesture_id)
diff --git a/gtk/gtkwidget.h b/gtk/gtkwidget.h
index f4ad657..407dc9f 100644
--- a/gtk/gtkwidget.h
+++ b/gtk/gtkwidget.h
@@ -957,10 +957,10 @@ GdkModifierType   gtk_widget_get_modifier_mask (GtkWidget         *widget,
                                                 GdkModifierIntent  intent);
 
 /* Gestures */
-void gtk_widget_enable_gesture (GtkWidget       *widget,
-                                GtkGestureType   gesture);
+void gtk_widget_enable_gesture  (GtkWidget      *widget,
+				 guint           gesture_id);
 void gtk_widget_disable_gesture (GtkWidget      *widget,
-                                 GtkGestureType  gesture);
+				 guint           gesture_id);
 
 G_END_DECLS