[gtk/ebassi/gidocgen: 396/481] padcontroller: Convert docs

[Emmanuele Bassi <ebassi src gnome org>]

commit b4839b7cf0750f515677e5d7ae78d3e985b1e9d3
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Mar 1 01:45:04 2021 -0500

    padcontroller: Convert docs

 gtk/gtkpadcontroller.c | 121 ++++++++++++++++++++++++++-----------------------
 1 file changed, 64 insertions(+), 57 deletions(-)
---
diff --git a/gtk/gtkpadcontroller.c b/gtk/gtkpadcontroller.c
index c4871aa981..ddee7931e6 100644
--- a/gtk/gtkpadcontroller.c
+++ b/gtk/gtkpadcontroller.c
@@ -18,53 +18,55 @@
  */
 
 /**
- * SECTION:gtkpadcontroller
- * @Short_description: Controller for drawing tablet pads
- * @Title: GtkPadController
- * @See_also: #GtkEventController, #GdkDevicePad
+ * GtkPadController:
  *
- * #GtkPadController is an event controller for the pads found in drawing
- * tablets (The collection of buttons and tactile sensors often found around
- * the stylus-sensitive area).
+ * `GtkPadController` is an event controller for the pads found in drawing
+ * tablets.
+ *
+ * Pads are the collection of buttons and tactile sensors often found around
+ * the stylus-sensitive area.
  *
  * These buttons and sensors have no implicit meaning, and by default they
- * perform no action, this event controller is provided to map those to
- * #GAction objects, thus letting the application give those a more semantic
- * meaning.
+ * perform no action. `GtkPadController` is provided to map those to
+ * `GAction` objects, thus letting the application give them a more
+ * semantic meaning.
+ *
+ * Buttons and sensors are not constrained to triggering a single action,
+ * some %GDK_SOURCE_TABLET_PAD devices feature multiple "modes". All these
+ * input elements have one current mode, which may determine the final action
+ * being triggered.
  *
- * Buttons and sensors are not constrained to triggering a single action, some
- * %GDK_SOURCE_TABLET_PAD devices feature multiple "modes", all these input
- * elements have one current mode, which may determine the final action
- * being triggered. Pad devices often divide buttons and sensors into groups,
- * all elements in a group share the same current mode, but different groups
- * may have different modes. See gdk_device_pad_get_n_groups() and
- * gdk_device_pad_get_group_n_modes().
+ * Pad devices often divide buttons and sensors into groups. All elements
+ * in a group share the same current mode, but different groups may have
+ * different modes. See [method@Gdk.DevicePad.get_n_groups] and
+ * [method@Gdk.DevicePad.get_group_n_modes].
  *
  * Each of the actions that a given button/strip/ring performs for a given
- * mode is defined by #GtkPadActionEntry, it contains an action name that
- * will be looked up in the given #GActionGroup and activated whenever the
- * specified input element and mode are triggered.
+ * mode is defined by a [struct@Gtk.PadActionEntry]. It contains an action
+ * name that will be looked up in the given `GActionGroup` and activated
+ * whenever the specified input element and mode are triggered.
  *
- * A simple example of #GtkPadController usage, assigning button 1 in all
+ * A simple example of `GtkPadController` usage: Assigning button 1 in all
  * modes and pad devices to an "invert-selection" action:
- * |[
- *   GtkPadActionEntry *pad_actions[] = {
- *     { GTK_PAD_ACTION_BUTTON, 1, -1, "Invert selection", "pad-actions.invert-selection" },
- *     …
- *   };
  *
+ * ```c
+ * GtkPadActionEntry *pad_actions[] = {
+ *   { GTK_PAD_ACTION_BUTTON, 1, -1, "Invert selection", "pad-actions.invert-selection" },
  *   …
- *   action_group = g_simple_action_group_new ();
- *   action = g_simple_action_new ("pad-actions.invert-selection", NULL);
- *   g_signal_connect (action, "activate", on_invert_selection_activated, NULL);
- *   g_action_map_add_action (G_ACTION_MAP (action_group), action);
- *   …
- *   pad_controller = gtk_pad_controller_new (action_group, NULL);
- * ]|
+ * };
+ *
+ * …
+ * action_group = g_simple_action_group_new ();
+ * action = g_simple_action_new ("pad-actions.invert-selection", NULL);
+ * g_signal_connect (action, "activate", on_invert_selection_activated, NULL);
+ * g_action_map_add_action (G_ACTION_MAP (action_group), action);
+ * …
+ * pad_controller = gtk_pad_controller_new (action_group, NULL);
+ * ```
  *
  * The actions belonging to rings/strips will be activated with a parameter
  * of type %G_VARIANT_TYPE_DOUBLE bearing the value of the given axis, it
- * is required that those are made stateful and accepting this #GVariantType.
+ * is required that those are made stateful and accepting this `GVariantType`.
  */
 
 #include "config.h"
@@ -389,24 +391,26 @@ gtk_pad_controller_init (GtkPadController *controller)
 
 /**
  * gtk_pad_controller_new:
- * @group: #GActionGroup to trigger actions from
+ * @group: `GActionGroup` to trigger actions from
  * @pad: (nullable): A %GDK_SOURCE_TABLET_PAD device, or %NULL to handle all pads
  *
- * Creates a new #GtkPadController that will associate events from @pad to
- * actions. A %NULL pad may be provided so the controller manages all pad devices
- * generically, it is discouraged to mix #GtkPadController objects with %NULL
- * and non-%NULL @pad argument on the same toplevel window, as execution order
- * is not guaranteed.
+ * Creates a new `GtkPadController` that will associate events from @pad to
+ * actions.
+ *
+ * A %NULL pad may be provided so the controller manages all pad devices
+ * generically, it is discouraged to mix `GtkPadController` objects with
+ * %NULL and non-%NULL @pad argument on the same toplevel window, as execution
+ * order is not guaranteed.
  *
- * The #GtkPadController is created with no mapped actions. In order to map pad
- * events to actions, use gtk_pad_controller_set_action_entries() or
- * gtk_pad_controller_set_action().
+ * The `GtkPadController` is created with no mapped actions. In order to
+ * map pad events to actions, use [method@Gtk.PadController.set_action_entries]
+ * or [method@Gtk.PadController.set_action].
  *
- * Be aware that pad events will only be delivered to #GtkWindows, so adding a pad
- * controller to any other type of widget will not have an effect.
+ * Be aware that pad events will only be delivered to `GtkWindow`s, so adding
+ * a pad controller to any other type of widget will not have an effect.
  *
- * Returns: A newly created #GtkPadController
- **/
+ * Returns: A newly created `GtkPadController`
+ */
 GtkPadController *
 gtk_pad_controller_new (GActionGroup *group,
                         GdkDevice    *pad)
@@ -465,13 +469,15 @@ gtk_pad_controller_add_entry (GtkPadController        *controller,
 
 /**
  * gtk_pad_controller_set_action_entries:
- * @controller: a #GtkPadController
+ * @controller: a `GtkPadController`
  * @entries: (array length=n_entries): the action entries to set on @controller
  * @n_entries: the number of elements in @entries
  *
- * This is a convenience function to add a group of action entries on
- * @controller. See #GtkPadActionEntry and gtk_pad_controller_set_action().
- **/
+ * A convenience function to add a group of action entries on
+ * @controller.
+ *
+ * See [struct@Gtk.PadActionEntry] and [method@Gtk.PadController.set_action].
+ */
 void
 gtk_pad_controller_set_action_entries (GtkPadController        *controller,
                                        const GtkPadActionEntry *entries,
@@ -488,7 +494,7 @@ gtk_pad_controller_set_action_entries (GtkPadController        *controller,
 
 /**
  * gtk_pad_controller_set_action:
- * @controller: a #GtkPadController
+ * @controller: a `GtkPadController`
  * @type: the type of pad feature that will trigger this action
  * @index: the 0-indexed button/ring/strip number that will trigger this action
  * @mode: the mode that will trigger this action, or -1 for all modes.
@@ -496,15 +502,16 @@ gtk_pad_controller_set_action_entries (GtkPadController        *controller,
  *   be deemed user-visible.
  * @action_name: action name that will be activated in the #GActionGroup
  *
- * Adds an individual action to @controller. This action will only be activated
- * if the given button/ring/strip number in @index is interacted while
- * the current mode is @mode. -1 may be used for simple cases, so the action
- * is triggered on all modes.
+ * Adds an individual action to @controller.
+ *
+ * This action will only be activated if the given button/ring/strip number
+ * in @index is interacted while the current mode is @mode. -1 may be used
+ * for simple cases, so the action is triggered on all modes.
  *
  * The given @label should be considered user-visible, so internationalization
  * rules apply. Some windowing systems may be able to use those for user
  * feedback.
- **/
+ */
 void
 gtk_pad_controller_set_action (GtkPadController *controller,
                                GtkPadActionType  type,