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

[Carlos Garnacho <carlosg src gnome org>]

commit 9b140bfa735b066c1d2d7cbdf904073c859636bd
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 d3d2b3f..f6fcf25 100644
--- a/docs/reference/gtk/gtk3-sections.txt
+++ b/docs/reference/gtk/gtk3-sections.txt
@@ -5306,6 +5306,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 e6cba18..2e0535a 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -3154,6 +3154,15 @@ gtk_widget_class_init (GtkWidgetClass *klass)
 		  G_TYPE_INT,
 		  G_TYPE_INT);
 
+  /**
+   * 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),
@@ -14613,6 +14622,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)
@@ -14641,6 +14657,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 fc76377..67d08da 100644
--- a/gtk/gtkwidget.h
+++ b/gtk/gtkwidget.h
@@ -914,10 +914,10 @@ void              gtk_widget_release_captured_events (GtkWidget *widget,
                                                       gboolean   emit);
 
 /* 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