[gtk/ebassi/gidocgen: 456/465] shortcuttrigger: Convert docs

From: Emmanuele Bassi <ebassi src gnome org>
To: commits-list gnome org
Cc:
Subject: [gtk/ebassi/gidocgen: 456/465] shortcuttrigger: Convert docs
Date: Mon, 8 Mar 2021 22:26:23 +0000 (UTC)

commit 569aa06e930553efbefffb68d10d576cd042cd02
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Mar 1 22:54:48 2021 -0500

    shortcuttrigger: Convert docs

 gtk/gtkshortcuttrigger.c | 189 +++++++++++++++++++++++++----------------------
 gtk/gtkshortcuttrigger.h |   6 --
 2 files changed, 100 insertions(+), 95 deletions(-)
---
diff --git a/gtk/gtkshortcuttrigger.c b/gtk/gtkshortcuttrigger.c
index fab339fe54..2e99c9bc63 100644
--- a/gtk/gtkshortcuttrigger.c
+++ b/gtk/gtkshortcuttrigger.c
@@ -20,21 +20,19 @@
  */
 
 /**
- * SECTION:gtkshortcuttrigger
- * @Title: GtkShortcutTrigger
- * @Short_description: Triggers to track if shortcuts should be activated
- * @See_also: #GtkShortcut
+ * GtkShortcutTrigger:
  *
- * #GtkShortcutTrigger is the object used to track if a #GtkShortcut should be
- * activated. For this purpose, gtk_shortcut_trigger_trigger() can be called
- * on a #GdkEvent.
+ * `GtkShortcutTrigger` tracks how a `GtkShortcut` should be activated.
  *
- * #GtkShortcutTriggers contain functions that allow easy presentation to end
- * users as well as being printed for debugging.
+ * To find out if a `GtkShortcutTrigger` triggers, you can call
+ * [method@Gtk.ShortcutTrigger.trigger] on a `GdkEvent`.
  *
- * All #GtkShortcutTriggers are immutable, you can only specify their properties
- * during construction. If you want to change a trigger, you have to replace it
- * with a new one.
+ * `GtkShortcutTriggers` contain functions that allow easy presentation
+ * to end users as well as being printed for debugging.
+ *
+ * All `GtkShortcutTriggers` are immutable, you can only specify their
+ * properties during construction. If you want to change a trigger, you
+ * have to replace it with a new one.
  */
 
 #include "config.h"
@@ -86,7 +84,7 @@ gtk_shortcut_trigger_init (GtkShortcutTrigger *self)
 
 /**
  * gtk_shortcut_trigger_trigger:
- * @self: a #GtkShortcutTrigger
+ * @self: a `GtkShortcutTrigger`
  * @event: the event to check
  * @enable_mnemonics: %TRUE if mnemonics should trigger. Usually the
  *     value of this property is determined by checking that the passed
@@ -95,7 +93,7 @@ gtk_shortcut_trigger_init (GtkShortcutTrigger *self)
  * Checks if the given @event triggers @self.
  *
  * Returns: Whether the event triggered the shortcut
- **/
+ */
 GdkKeyMatch
 gtk_shortcut_trigger_trigger (GtkShortcutTrigger *self,
                               GdkEvent           *event,
@@ -110,23 +108,24 @@ gtk_shortcut_trigger_trigger (GtkShortcutTrigger *self,
  * gtk_shortcut_trigger_parse_string: (constructor)
  * @string: the string to parse
  *
- * Tries to parse the given string into a trigger. On success,
- * the parsed trigger is returned. When parsing failed, %NULL is
- * returned.
+ * Tries to parse the given string into a trigger.
+ *
+ * On success, the parsed trigger is returned.
+ * When parsing failed, %NULL is returned.
  *
  * The accepted strings are:
  *
- *   - `never`, for #GtkNeverTrigger
- *   - a string parsed by gtk_accelerator_parse(), for a #GtkKeyvalTrigger, e.g. `<Control>C`
- *   - underscore, followed by a single character, for MnemonicTrigger, e.g. `_l`
+ *   - `never`, for `GtkNeverTrigger`
+ *   - a string parsed by gtk_accelerator_parse(), for a `GtkKeyvalTrigger`, e.g. `<Control>C`
+ *   - underscore, followed by a single character, for `GtkMnemonicTrigger`, e.g. `_l`
  *   - two valid trigger strings, separated by a `|` character, for a
- *     #GtkAlternativeTrigger: `<Control>q|<Control>w`
+ *     `GtkAlternativeTrigger`: `<Control>q|<Control>w`
  *
  * Note that you will have to escape the `<` and `>` characters when specifying
  * triggers in XML files, such as GtkBuilder ui files. Use `&lt;` instead of
  * `<` and `&gt;` instead of `>`.
  *
- * Returns: (nullable) (transfer full): a new #GtkShortcutTrigger
+ * Returns: (nullable) (transfer full): a new `GtkShortcutTrigger`
  *   or %NULL on error
  */
 GtkShortcutTrigger *
@@ -196,10 +195,11 @@ gtk_shortcut_trigger_parse_string (const char *string)
 
 /**
  * gtk_shortcut_trigger_to_string:
- * @self: a #GtkShortcutTrigger
+ * @self: a `GtkShortcutTrigger`
  *
  * Prints the given trigger into a human-readable string.
- * This is a small wrapper around gtk_shortcut_trigger_print()
+ *
+ * This is a small wrapper around [method@Gtk.ShortcutTrigger.print]
  * to help when debugging.
  *
  * Returns: (transfer full): a new string
@@ -220,8 +220,8 @@ gtk_shortcut_trigger_to_string (GtkShortcutTrigger *self)
 
 /**
  * gtk_shortcut_trigger_print:
- * @self: a #GtkShortcutTrigger
- * @string: a #GString to print into
+ * @self: a `GtkShortcutTrigger`
+ * @string: a `GString` to print into
  *
  * Prints the given trigger into a string for the developer.
  * This is meant for debugging and logging.
@@ -241,12 +241,14 @@ gtk_shortcut_trigger_print (GtkShortcutTrigger *self,
 
 /**
  * gtk_shortcut_trigger_to_label:
- * @self: a #GtkShortcutTrigger
- * @display: #GdkDisplay to print for
+ * @self: a `GtkShortcutTrigger`
+ * @display: `GdkDisplay` to print for
  *
- * Gets textual representation for the given trigger. This
- * function is returning a translated string for presentation
- * to end users for example in menu items or in help texts.
+ * Gets textual representation for the given trigger.
+ *
+ * This function is returning a translated string for
+ * presentation to end users for example in menu items
+ * or in help texts.
  *
  * The @display in use may influence the resulting string in
  * various forms, such as resolving hardware keycodes or by
@@ -256,7 +258,7 @@ gtk_shortcut_trigger_print (GtkShortcutTrigger *self,
  * not guaranteed to stay identical.
  *
  * Returns: (transfer full): a new string
- **/
+ */
 char *
 gtk_shortcut_trigger_to_label (GtkShortcutTrigger *self,
                                GdkDisplay         *display)
@@ -273,13 +275,14 @@ gtk_shortcut_trigger_to_label (GtkShortcutTrigger *self,
 
 /**
  * gtk_shortcut_trigger_print_label:
- * @self: a #GtkShortcutTrigger
- * @display: #GdkDisplay to print for
- * @string: a #GString to print into
+ * @self: a `GtkShortcutTrigger`
+ * @display: `GdkDisplay` to print for
+ * @string: a `GString` to print into
  *
- * Prints the given trigger into a string. This function is
- * returning a translated string for presentation to end users
- * for example in menu items or in help texts.
+ * Prints the given trigger into a string.
+ *
+ * This function is returning a translated string for presentation
+ * to end users for example in menu items or in help texts.
  *
  * The @display in use may influence the resulting string in
  * various forms, such as resolving hardware keycodes or by
@@ -306,20 +309,20 @@ gtk_shortcut_trigger_print_label (GtkShortcutTrigger *self,
 
 /**
  * gtk_shortcut_trigger_hash:
- * @trigger: (type GtkShortcutTrigger): a #GtkShortcutTrigger
+ * @trigger: (type GtkShortcutTrigger): a `GtkShortcutTrigger`
  *
- * Generates a hash value for a #GtkShortcutTrigger.
+ * Generates a hash value for a `GtkShortcutTrigger`.
  *
  * The output of this function is guaranteed to be the same for a given
- * value only per-process.  It may change between different processor
- * architectures or even different versions of GTK.  Do not use this
+ * value only per-process. It may change between different processor
+ * architectures or even different versions of GTK. Do not use this
  * function as a basis for building protocols or file formats.
  *
  * The types of @trigger is #gconstpointer only to allow use of this
- * function with #GHashTable. They must each be a #GtkShortcutTrigger.
+ * function with #GHashTable. They must each be a `GtkShortcutTrigger`.
  *
  * Returns: a hash value corresponding to @trigger
- **/
+ */
 guint
 gtk_shortcut_trigger_hash (gconstpointer trigger)
 {
@@ -332,16 +335,16 @@ gtk_shortcut_trigger_hash (gconstpointer trigger)
 
 /**
  * gtk_shortcut_trigger_equal:
- * @trigger1: (type GtkShortcutTrigger): a #GtkShortcutTrigger
- * @trigger2: (type GtkShortcutTrigger): a #GtkShortcutTrigger
+ * @trigger1: (type GtkShortcutTrigger): a `GtkShortcutTrigger`
+ * @trigger2: (type GtkShortcutTrigger): a `GtkShortcutTrigger`
  *
  * Checks if @trigger1 and @trigger2 trigger under the same conditions.
  *
  * The types of @one and @two are #gconstpointer only to allow use of this
- * function with #GHashTable. They must each be a #GtkShortcutTrigger.
+ * function with #GHashTable. They must each be a `GtkShortcutTrigger`.
  *
  * Returns: %TRUE if @trigger1 and @trigger2 are equal
- **/
+ */
 gboolean
 gtk_shortcut_trigger_equal (gconstpointer trigger1,
                             gconstpointer trigger2)
@@ -351,17 +354,18 @@ gtk_shortcut_trigger_equal (gconstpointer trigger1,
 
 /**
  * gtk_shortcut_trigger_compare:
- * @trigger1: (type GtkShortcutTrigger): a #GtkShortcutTrigger
- * @trigger2: (type GtkShortcutTrigger): a #GtkShortcutTrigger
- * 
+ * @trigger1: (type GtkShortcutTrigger): a `GtkShortcutTrigger`
+ * @trigger2: (type GtkShortcutTrigger): a `GtkShortcutTrigger`
+ *
  * The types of @trigger1 and @trigger2 are #gconstpointer only to allow
- * use of this function as a #GCompareFunc. They must each be a
- * #GtkShortcutTrigger.
+ * use of this function as a #GCompareFunc.
+ *
+ * They must each be a `GtkShortcutTrigger`.
  *
  * Returns: An integer less than, equal to, or greater than zero if
  *     @trigger1 is found, respectively, to be less than, to match,
  *     or be greater than @trigger2.
- **/
+ */
 int
 gtk_shortcut_trigger_compare (gconstpointer trigger1,
                               gconstpointer trigger2)
@@ -475,9 +479,11 @@ gtk_never_trigger_init (GtkNeverTrigger *self)
 /**
  * gtk_never_trigger_get:
  *
- * Gets the never trigger. This is a singleton for a trigger
- * that never triggers. Use this trigger instead of %NULL
- * because it implements all virtual functions.
+ * Gets the never trigger.
+ *
+ * This is a singleton for a trigger that never triggers.
+ * Use this trigger instead of %NULL because it implements
+ * all virtual functions.
  *
  * Returns: (type GtkNeverTrigger) (transfer none): The never trigger
  */
@@ -647,7 +653,7 @@ gtk_keyval_trigger_class_init (GtkKeyvalTriggerClass *klass)
   trigger_class->print_label = gtk_keyval_trigger_print_label;
 
   /**
-   * GtkKeyvalTrigger:keyval:
+   * GtkKeyvalTrigger:keyval: (attributes org.gtk.Property.get=gtk_keyval_trigger_get_keyval)
    *
    * The key value for the trigger.
    */
@@ -662,7 +668,7 @@ gtk_keyval_trigger_class_init (GtkKeyvalTriggerClass *klass)
                        G_PARAM_READWRITE);
 
   /**
-   * GtkKeyvalTrigger:modifiers:
+   * GtkKeyvalTrigger:modifiers: (attributes org.gtk.Property.get=gtk_keyval_trigger_get_modifiers)
    *
    * The key modifiers for the trigger.
    */
@@ -689,10 +695,10 @@ gtk_keyval_trigger_init (GtkKeyvalTrigger *self)
  * @keyval: The keyval to trigger for
  * @modifiers: the modifiers that need to be present
  *
- * Creates a #GtkShortcutTrigger that will trigger whenever
+ * Creates a `GtkShortcutTrigger` that will trigger whenever
  * the key with the given @keyval and @modifiers is pressed.
  *
- * Returns: A new #GtkShortcutTrigger
+ * Returns: A new `GtkShortcutTrigger`
  */
 GtkShortcutTrigger *
 gtk_keyval_trigger_new (guint           keyval,
@@ -705,14 +711,14 @@ gtk_keyval_trigger_new (guint           keyval,
 }
 
 /**
- * gtk_keyval_trigger_get_modifiers:
- * @self: a keyval #GtkShortcutTrigger
+ * gtk_keyval_trigger_get_modifiers: (attributes org.gtk.Method.get_property=modifiers)
+ * @self: a keyval `GtkShortcutTrigger`
  *
  * Gets the modifiers that must be present to succeed
  * triggering @self.
  *
  * Returns: the modifiers
- **/
+ */
 GdkModifierType
 gtk_keyval_trigger_get_modifiers (GtkKeyvalTrigger *self)
 {
@@ -722,14 +728,14 @@ gtk_keyval_trigger_get_modifiers (GtkKeyvalTrigger *self)
 }
 
 /**
- * gtk_keyval_trigger_get_keyval:
- * @self: a keyval #GtkShortcutTrigger
+ * gtk_keyval_trigger_get_keyval: (attributes org.gtk.Method.get_property=keyval)
+ * @self: a keyval `GtkShortcutTrigger`
  *
  * Gets the keyval that must be pressed to succeed
  * triggering @self.
  *
  * Returns: the keyval
- **/
+ */
 guint
 gtk_keyval_trigger_get_keyval (GtkKeyvalTrigger *self)
 {
@@ -903,7 +909,7 @@ gtk_mnemonic_trigger_class_init (GtkMnemonicTriggerClass *klass)
   trigger_class->print_label = gtk_mnemonic_trigger_print_label;
 
   /**
-   * GtkMnemonicTrigger:keyval:
+   * GtkMnemonicTrigger:keyval: (attributes org.gtk.Property.get=gtk_mnemonic_trigger_get_keyval)
    *
    * The key value for the trigger.
    */
@@ -929,13 +935,13 @@ gtk_mnemonic_trigger_init (GtkMnemonicTrigger *self)
  * gtk_mnemonic_trigger_new:
  * @keyval: The keyval to trigger for
  *
- * Creates a #GtkShortcutTrigger that will trigger whenever the key with
+ * Creates a `GtkShortcutTrigger` that will trigger whenever the key with
  * the given @keyval is pressed and mnemonics have been activated.
  *
  * Mnemonics are activated by calling code when a key event with the right
  * modifiers is detected.
  *
- * Returns: (transfer full) (type GtkMnemonicTrigger): A new #GtkShortcutTrigger
+ * Returns: (transfer full) (type GtkMnemonicTrigger): A new `GtkShortcutTrigger`
  */
 GtkShortcutTrigger *
 gtk_mnemonic_trigger_new (guint keyval)
@@ -946,13 +952,13 @@ gtk_mnemonic_trigger_new (guint keyval)
 }
 
 /**
- * gtk_mnemonic_trigger_get_keyval:
- * @self: a mnemonic #GtkShortcutTrigger
+ * gtk_mnemonic_trigger_get_keyval: (attributes org.gtk.Method.get_property=keyval)
+ * @self: a mnemonic `GtkShortcutTrigger`
  *
  * Gets the keyval that must be pressed to succeed triggering @self.
  *
  * Returns: the keyval
- **/
+ */
 guint
 gtk_mnemonic_trigger_get_keyval (GtkMnemonicTrigger *self)
 {
@@ -1149,9 +1155,9 @@ gtk_alternative_trigger_class_init (GtkAlternativeTriggerClass *klass)
   trigger_class->print_label = gtk_alternative_trigger_print_label;
 
   /**
-   * GtkAlternativeTrigger:first:
+   * GtkAlternativeTrigger:first: (attributes org.gtk.Property.get=gtk_alternative_trigger_get_first)
    *
-   * The first #GtkShortcutTrigger to check.
+   * The first `GtkShortcutTrigger` to check.
    */
   alternative_props[ALTERNATIVE_PROP_FIRST] =
     g_param_spec_object (I_("first"),
@@ -1161,10 +1167,11 @@ gtk_alternative_trigger_class_init (GtkAlternativeTriggerClass *klass)
                          G_PARAM_STATIC_STRINGS |
                          G_PARAM_CONSTRUCT_ONLY |
                          G_PARAM_READWRITE);
+
   /**
-   * GtkAlternativeTrigger:second:
+   * GtkAlternativeTrigger:second: (attributes org.gtk.Property.get=gtk_alternative_trigger_get_second)
    *
-   * The second #GtkShortcutTrigger to check.
+   * The second `GtkShortcutTrigger` to check.
    */
   alternative_props[ALTERNATIVE_PROP_SECOND] =
     g_param_spec_object (I_("second"),
@@ -1188,13 +1195,13 @@ gtk_alternative_trigger_init (GtkAlternativeTrigger *self)
  * @first: (transfer full): The first trigger that may trigger
  * @second: (transfer full): The second trigger that may trigger
  *
- * Creates a #GtkShortcutTrigger that will trigger whenever
+ * Creates a `GtkShortcutTrigger` that will trigger whenever
  * either of the two given triggers gets triggered.
  *
  * Note that nesting is allowed, so if you want more than two
  * alternative, create a new alternative trigger for each option.
  *
- * Returns: a new #GtkShortcutTrigger
+ * Returns: a new `GtkShortcutTrigger`
  */
 GtkShortcutTrigger *
 gtk_alternative_trigger_new (GtkShortcutTrigger *first,
@@ -1217,15 +1224,17 @@ gtk_alternative_trigger_new (GtkShortcutTrigger *first,
 }
 
 /**
- * gtk_alternative_trigger_get_first:
- * @self: an alternative #GtkShortcutTrigger
+ * gtk_alternative_trigger_get_first: (attributes org.gtk.Method.get_property=first)
+ * @self: an alternative `GtkShortcutTrigger`
  *
  * Gets the first of the two alternative triggers that may
- * trigger @self. gtk_alternative_trigger_get_second() will
- * return the other one.
+ * trigger @self.
+ *
+ * [method@Gtk.AlternativeTrigger.get_second] will return
+ * the other one.
  *
  * Returns: (transfer none): the first alternative trigger
- **/
+ */
 GtkShortcutTrigger *
 gtk_alternative_trigger_get_first (GtkAlternativeTrigger *self)
 {
@@ -1235,15 +1244,17 @@ gtk_alternative_trigger_get_first (GtkAlternativeTrigger *self)
 }
 
 /**
- * gtk_alternative_trigger_get_second:
- * @self: an alternative #GtkShortcutTrigger
+ * gtk_alternative_trigger_get_second: (attributes org.gtk.Method.get_property=second)
+ * @self: an alternative `GtkShortcutTrigger`
  *
  * Gets the second of the two alternative triggers that may
- * trigger @self. gtk_alternative_trigger_get_first() will
- * return the other one.
+ * trigger @self.
+ *
+ * [method@Gtk.AlternativeTrigger.get_first] will return
+ * the other one.
  *
  * Returns: (transfer none): the second alternative trigger
- **/
+ */
 GtkShortcutTrigger *
 gtk_alternative_trigger_get_second (GtkAlternativeTrigger *self)
 {
diff --git a/gtk/gtkshortcuttrigger.h b/gtk/gtkshortcuttrigger.h
index 8fae538f29..7d42489d91 100644
--- a/gtk/gtkshortcuttrigger.h
+++ b/gtk/gtkshortcuttrigger.h
@@ -30,12 +30,6 @@ G_BEGIN_DECLS
 
 #define GTK_TYPE_SHORTCUT_TRIGGER (gtk_shortcut_trigger_get_type ())
 
-/**
- * GtkShortcutTrigger:
- *
- * A trigger for a key shortcut.
- */
-
 GDK_AVAILABLE_IN_ALL
 GDK_DECLARE_INTERNAL_TYPE (GtkShortcutTrigger, gtk_shortcut_trigger, GTK, SHORTCUT_TRIGGER, GObject)
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]