[gtk/ebassi/gidocgen: 386/500] eventcontroller: Convert docs

[Emmanuele Bassi <ebassi src gnome org>]

commit d7e0af62e33d997fb3b5794db58099b2a03dd179
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Mar 1 01:33:51 2021 -0500

    eventcontroller: Convert docs

 gtk/gtkeventcontroller.c | 109 ++++++++++++++++++++++++-----------------------
 1 file changed, 56 insertions(+), 53 deletions(-)
---
diff --git a/gtk/gtkeventcontroller.c b/gtk/gtkeventcontroller.c
index 7d1c9ea1d7..b4841c10fa 100644
--- a/gtk/gtkeventcontroller.c
+++ b/gtk/gtkeventcontroller.c
@@ -19,15 +19,20 @@
  */
 
 /**
- * SECTION:gtkeventcontroller
- * @Short_description: Self-contained handler of series of events
- * @Title: GtkEventController
- * @See_also: #GtkGesture
- *
- * #GtkEventController is a base, low-level implementation for event
- * controllers: ancillary object associated to widgets, which react
- * to a series of #GdkEvents, and possibly trigger actions as a
- * consequence.
+ * GtkEventController:
+ *
+ * `GtkEventController` is the base class for event controllers.
+ *
+ * These are ancillary objects associated to widgets, which react
+ * to `GdkEvents`, and possibly trigger actions as a consequence.
+ *
+ * Event controllers are added to a widget with
+ * [method@Gtk.Widget.add_controller]. It is rarely necessary to
+ * explicitly remove a controller with [method@Gtk.Widget.remove_controller].
+ *
+ * See the chapter of [input handling](input-handling.html) for
+ * an overview of the basic concepts, such as the capture and bubble
+ * phases of even propagation.
  */
 
 #include "config.h"
@@ -190,9 +195,9 @@ gtk_event_controller_class_init (GtkEventControllerClass *klass)
   object_class->get_property = gtk_event_controller_get_property;
 
   /**
-   * GtkEventController:widget:
+   * GtkEventController:widget: (attributes org.gtk.Property.get=gtk_event_controller_get_widget)
    *
-   * The widget receiving the #GdkEvents that the controller will handle.
+   * The widget receiving the `GdkEvents` that the controller will handle.
    */
   properties[PROP_WIDGET] =
       g_param_spec_object ("widget",
@@ -202,7 +207,7 @@ gtk_event_controller_class_init (GtkEventControllerClass *klass)
                            GTK_PARAM_READABLE);
 
   /**
-   * GtkEventController:propagation-phase:
+   * GtkEventController:propagation-phase: (attributes 
org.gtk.Property.get=gtk_event_controller_get_propagation_phase 
org.gtk.Property.set=gtk_event_controller_set_propagation_phase)
    *
    * The propagation phase at which this controller will handle events.
    */
@@ -215,7 +220,7 @@ gtk_event_controller_class_init (GtkEventControllerClass *klass)
                          GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkEventController:propagation-limit:
+   * GtkEventController:propagation-limit: (attributes 
org.gtk.Property.get=gtk_event_controller_get_propagation_limit 
org.gtk.Property.set=gtk_event_controller_set_propagation_limit)
    *
    * The limit for which events this controller will handle.
    */
@@ -228,7 +233,7 @@ gtk_event_controller_class_init (GtkEventControllerClass *klass)
                          GTK_PARAM_READWRITE|G_PARAM_EXPLICIT_NOTIFY);
 
   /**
-   * GtkEventController:name:
+   * GtkEventController:name: (attributes org.gtk.Property.get=gtk_event_controller_get_name 
org.gtk.Property.set=gtk_event_controller_set_name)
    *
    * The name for this controller, typically used for debugging purposes.
    */
@@ -322,10 +327,10 @@ gtk_event_controller_filter_crossing (GtkEventController    *controller,
   return FALSE;
 }
 
-/*
+/*< private >
  * gtk_event_controller_handle_event:
- * @controller: a #GtkEventController
- * @event: a #GdkEvent
+ * @controller: a `GtkEventController`
+ * @event: a `GdkEvent`
  * @target: the target widget
  * @x: event position in widget coordinates, or 0 if not a pointer event
  * @y: event position in widget coordinates, or 0 if not a pointer event
@@ -334,8 +339,8 @@ gtk_event_controller_filter_crossing (GtkEventController    *controller,
  * and the controller actions triggered.
  *
  * Returns: %TRUE if the event was potentially useful to trigger the
- *          controller action
- **/
+ *   controller action
+ */
 gboolean
 gtk_event_controller_handle_event (GtkEventController *controller,
                                    GdkEvent           *event,
@@ -402,12 +407,12 @@ gtk_event_controller_handle_crossing (GtkEventController    *controller,
 }
 
 /**
- * gtk_event_controller_get_widget:
- * @controller: a #GtkEventController
+ * gtk_event_controller_get_widget: (attributes org.gtk.Method.get_property=widget)
+ * @controller: a `GtkEventController`
  *
  * Returns the #GtkWidget this controller relates to.
  *
- * Returns: (transfer none): a #GtkWidget
+ * Returns: (transfer none): a `GtkWidget`
  **/
 GtkWidget *
 gtk_event_controller_get_widget (GtkEventController *controller)
@@ -423,12 +428,10 @@ gtk_event_controller_get_widget (GtkEventController *controller)
 
 /**
  * gtk_event_controller_reset:
- * @controller: a #GtkEventController
+ * @controller: a `GtkEventController`
  *
- * Resets the @controller to a clean state. Every interaction
- * the controller did through gtk_event_controller_handle_event()
- * will be dropped at this point.
- **/
+ * Resets the @controller to a clean state.
+ */
 void
 gtk_event_controller_reset (GtkEventController *controller)
 {
@@ -443,13 +446,13 @@ gtk_event_controller_reset (GtkEventController *controller)
 }
 
 /**
- * gtk_event_controller_get_propagation_phase:
- * @controller: a #GtkEventController
+ * gtk_event_controller_get_propagation_phase: (attributes org.gtk.Method.get_property=propagation-phase)
+ * @controller: a `GtkEventController`
  *
  * Gets the propagation phase at which @controller handles events.
  *
  * Returns: the propagation phase
- **/
+ */
 GtkPropagationPhase
 gtk_event_controller_get_propagation_phase (GtkEventController *controller)
 {
@@ -463,16 +466,15 @@ gtk_event_controller_get_propagation_phase (GtkEventController *controller)
 }
 
 /**
- * gtk_event_controller_set_propagation_phase:
- * @controller: a #GtkEventController
+ * gtk_event_controller_set_propagation_phase: (attributes org.gtk.Method.set_property=propagation-phase)
+ * @controller: a `GtkEventController`
  * @phase: a propagation phase
  *
  * Sets the propagation phase at which a controller handles events.
  *
  * If @phase is %GTK_PHASE_NONE, no automatic event handling will be
- * performed, but other additional gesture maintenance will. In that phase,
- * the events can be managed by calling gtk_event_controller_handle_event().
- **/
+ * performed, but other additional gesture maintenance will.
+ */
 void
 gtk_event_controller_set_propagation_phase (GtkEventController  *controller,
                                             GtkPropagationPhase  phase)
@@ -496,8 +498,8 @@ gtk_event_controller_set_propagation_phase (GtkEventController  *controller,
 }
 
 /**
- * gtk_event_controller_get_propagation_limit:
- * @controller: a #GtkEventController
+ * gtk_event_controller_get_propagation_limit: (attributes org.gtk.Method.get_property=propagation-limit)
+ * @controller: a `GtkEventController`
  *
  * Gets the propagation limit of the event controller.
  *
@@ -516,8 +518,8 @@ gtk_event_controller_get_propagation_limit (GtkEventController *controller)
 }
 
 /**
- * gtk_event_controller_set_propagation_limit:
- * @controller: a #GtkEventController
+ * gtk_event_controller_set_propagation_limit: (attributes org.gtk.Method.set_property=propagation-limit)
+ * @controller: a `GtkEventController`
  * @limit: the propagation limit
  *
  * Sets the event propagation limit on the event controller.
@@ -545,8 +547,8 @@ gtk_event_controller_set_propagation_limit (GtkEventController  *controller,
 }
 
 /**
- * gtk_event_controller_get_name:
- * @controller: a #GtkEventController
+ * gtk_event_controller_get_name: (attributes org.gtk.Method.get_property=name)
+ * @controller: a `GtkEventController`
  *
  * Gets the name of @controller.
  */
@@ -561,12 +563,11 @@ gtk_event_controller_get_name (GtkEventController *controller)
 }
 
 /**
- * gtk_event_controller_set_name:
- * @controller: a #GtkEventController
+ * gtk_event_controller_set_name: (attributes org.gtk.Method.set_property=name)
+ * @controller: a `GtkEventController`
  * @name: a name for @controller
  *
- * Sets a name on the controller that can be used for
- * debugging.
+ * Sets a name on the controller that can be used for debugging.
  */
 void
 gtk_event_controller_set_name (GtkEventController *controller,
@@ -590,12 +591,13 @@ gtk_event_controller_get_target (GtkEventController *controller)
 
 /**
  * gtk_event_controller_get_current_event:
- * @controller: a #GtkEventController
+ * @controller: a `GtkEventController`
  *
  * Returns the event that is currently being handled by the
  * controller, and %NULL at other times.
  *
- * Returns: (nullable) (transfer none): the event is current handled by @controller
+ * Returns: (nullable) (transfer none): the event that is currently
+ *   handled by @controller
  */
 GdkEvent *
 gtk_event_controller_get_current_event (GtkEventController *controller)
@@ -607,12 +609,12 @@ gtk_event_controller_get_current_event (GtkEventController *controller)
 
 /**
  * gtk_event_controller_get_current_event_time:
- * @controller: a #GtkEventController
+ * @controller: a `GtkEventController`
  *
  * Returns the timestamp of the event that is currently being
  * handled by the controller, and 0 otherwise.
  *
- * Returns: timestamp of the event is current handled by @controller
+ * Returns: timestamp of the event is currently handled by @controller
  */
 guint32
 gtk_event_controller_get_current_event_time (GtkEventController *controller)
@@ -627,12 +629,13 @@ gtk_event_controller_get_current_event_time (GtkEventController *controller)
 
 /**
  * gtk_event_controller_get_current_event_device:
- * @controller: a #GtkEventController
+ * @controller: a `GtkEventController`
  *
  * Returns the device of the event that is currently being
  * handled by the controller, and %NULL otherwise.
  *
- * Returns: (nullable) (transfer none): device of the event is current handled by @controller
+ * Returns: (nullable) (transfer none): device of the event is
+ *   currently handled by @controller
  */
 GdkDevice *
 gtk_event_controller_get_current_event_device (GtkEventController *controller)
@@ -647,12 +650,12 @@ gtk_event_controller_get_current_event_device (GtkEventController *controller)
 
 /**
  * gtk_event_controller_get_current_event_state:
- * @controller: a #GtkEventController
+ * @controller: a `GtkEventController`
  *
  * Returns the modifier state of the event that is currently being
  * handled by the controller, and 0 otherwise.
  *
- * Returns: modifier state of the event is current handled by @controller
+ * Returns: modifier state of the event is currently handled by @controller
  */
 GdkModifierType
 gtk_event_controller_get_current_event_state (GtkEventController *controller)