[gtk+/gestures: 114/140] widget: Add docs for GtkGesture-related API

[Carlos Garnacho <carlosg src gnome org>]

commit 17dd304718ce6122e071ac81ee87fb65132a84de
Author: Carlos Garnacho <carlosg gnome org>
Date:   Thu Apr 10 13:45:38 2014 +0200

    widget: Add docs for GtkGesture-related API

 gtk/gtkwidget.c |   33 +++++++++++++++++++++++++++++++++
 1 files changed, 33 insertions(+), 0 deletions(-)
---
diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index ae2efdf..aa6f087 100644
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -16722,6 +16722,20 @@ _gtk_widget_has_controller (GtkWidget          *widget,
   return NULL;
 }
 
+/**
+ * gtk_widget_add_controller:
+ * @widget: a #GtkWidget, must be the same than the one passed on construction to @controller
+ * @controller: a #GtkEventController
+ *
+ * Adds @controller to the list of controllers that are triggered
+ * any time @widget receives events. the stage at which the events
+ * are delivered to @controller is mandated by
+ * gtk_event_controller_get_propagation_phase(). @widget will also take care
+ * of calling gtk_event_controller_reset() whenever input is grabbed
+ * elsewhere.
+ *
+ * Since: 3.14
+ **/
 void
 gtk_widget_add_controller (GtkWidget          *widget,
                            GtkEventController *controller)
@@ -16731,6 +16745,7 @@ gtk_widget_add_controller (GtkWidget          *widget,
 
   g_return_if_fail (GTK_IS_WIDGET (widget));
   g_return_if_fail (GTK_IS_EVENT_CONTROLLER (controller));
+  g_return_if_fail (widget == gtk_event_controller_get_widget (controller));
   g_return_if_fail (!_gtk_widget_has_controller (widget, controller));
 
   priv = widget->priv;
@@ -16756,6 +16771,13 @@ gtk_widget_add_controller (GtkWidget          *widget,
   _gtk_widget_update_evmask (widget);
 }
 
+/**
+ * gtk_widget_remove_controller:
+ * @widget: a #GtkWidget
+ * @controller: a #GtkEventController attached to @widget
+ *
+ * Removes @controller from the list of controllers managed by @widget.
+ **/
 void
 gtk_widget_remove_controller (GtkWidget          *widget,
                               GtkEventController *controller)
@@ -16784,6 +16806,17 @@ gtk_widget_remove_controller (GtkWidget          *widget,
   g_free (data);
 }
 
+/**
+ * gtk_widget_list_controllers:
+ * @widget: a #GtkWidget
+ *
+ * Returns the list of controllers that are managed by @widget.
+ *
+ * Returns: (transfer container) (element-type GtkEventController): the list of
+ *   controllers, free with g_list_free()
+ *
+ * Since: 3.14
+ **/
 GList *
 gtk_widget_list_controllers (GtkWidget *widget)
 {