From ec854fc503dd56dce11ed5c264ed27e78ccd19ef Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Sat, 4 Apr 2020 11:38:47 -0400
Subject: [PATCH] shortcuts: documentation fixes

Update symbol lists, and add examples for parsing triggers
and actions.
---
 docs/reference/gtk/gtk4-sections.txt | 39 ++++++++++++++++++----------
 gtk/gtkshortcutaction.c              | 19 ++++++++++++++
 gtk/gtkshortcuttrigger.c             |  6 ++---
 3 files changed, 48 insertions(+), 16 deletions(-)

diff --git a/docs/reference/gtk/gtk4-sections.txt b/docs/reference/gtk/gtk4-sections.txt
index c4088ea82c..e944c9256f 100644
--- a/docs/reference/gtk/gtk4-sections.txt
+++ b/docs/reference/gtk/gtk4-sections.txt
@@ -5958,11 +5958,9 @@ gtk_event_controller_motion_get_type
 <FILE>gtkshortcuttrigger</FILE>
 <TITLE>GtkShortcutTrigger</TITLE>
 GtkShortcutTrigger
-gtk_shortcut_trigger_ref
-gtk_shortcut_trigger_unref
-GtkShortcutTriggerType
-gtk_shortcut_trigger_get_trigger_type
-gtk_shortcut_trigger_parse_string
+GtkNeverTrigger
+
+GtkShortcutTriggerMatch
 gtk_shortcut_trigger_trigger
 gtk_shortcut_trigger_hash
 gtk_shortcut_trigger_equal
@@ -5971,16 +5969,28 @@ gtk_shortcut_trigger_to_string
 gtk_shortcut_trigger_print
 gtk_shortcut_trigger_to_label
 gtk_shortcut_trigger_print_label
+gtk_shortcut_trigger_parse_string
 
 <SUBSECTION>
+GtkKeyvalTrigger
 gtk_keyval_trigger_new
 gtk_keyval_trigger_get_modifiers
 gtk_keyval_trigger_get_keyval
 
 <SUBSECTION>
+GtkMnemonicTrigger
 gtk_mnemonic_trigger_new
 gtk_mnemonic_trigger_get_keyval
 
+<SUBSECTION>
+GtkAlternativeTrigger
+gtk_alternative_trigger_new
+gtk_alternative_trigger_get_first
+
+<SUBSECTION>
+GtkNeverTrigger
+gtk_never_trigger_get
+
 <SUBSECTION Private>
 gtk_shortcut_trigger_get_type
 </SECTION>
@@ -5989,33 +5999,36 @@ gtk_shortcut_trigger_get_type
 <FILE>gtkshortcutaction</FILE>
 <TITLE>GtkShortcutAction</TITLE>
 GtkShortcutAction
-gtk_shortcut_action_ref
-gtk_shortcut_action_unref
-GtkShortcutActionType
-gtk_shortcut_action_get_action_type
 gtk_shortcut_action_to_string
 gtk_shortcut_action_print
+gtk_shortcut_action_parse_string
 gtk_shortcut_action_activate
 
 <SUBSECTION>
-gtk_nothing_action_new
+GtkNothingAction
+gtk_nothing_action_get
 
 <SUBSECTION>
+GtkCallbackAction
 gtk_callback_action_new
 
 <SUBSECTION>
-gtk_mnemonic_action_new
+GtkMnemonicAction
+gtk_mnemonic_action_get
 
 <SUBSECTION>
-gtk_activate_action_new
+GtkActivateAction
+gtk_activate_action_get
 
 <SUBSECTION>
+GtkSignalAction
 gtk_signal_action_new
 gtk_signal_action_get_signal_name
 
 <SUBSECTION>
+GtkNamedAction
 gtk_named_action_new
-gtk_named_action_get_name
+gtk_named_action_get_action_name
 
 <SUBSECTION Private>
 gtk_shortcut_action_get_type
diff --git a/gtk/gtkshortcutaction.c b/gtk/gtkshortcutaction.c
index c1357d04e8..a117cf042e 100644
--- a/gtk/gtkshortcutaction.c
+++ b/gtk/gtkshortcutaction.c
@@ -183,6 +183,25 @@ string_is_function (const char *string,
   return g_strndup (string, len - 1);
 }
 
+/**
+ * gtk_shortcut_action_parse_string: (constructor)
+ * @string: the string to parse
+ *
+ * Tries to parse the given string into an action. On
+ * success, the parsed action is returned. When parsing
+ * failed, %NULL is returned.
+ *
+ * The accepted strings are:
+ *
+ *   - `nothing`, for #GtkNothingAction
+ *   - `activate`, for #GtkActivateAction
+ *   - `mnemonic-activate`, for #GtkMnemonicAction
+ *   - `action(NAME)`, for a #GtkNamedAction for the action named `NAME`
+ *   - `signal(NAME)`, for a #GtkSignalAction for the signal `NAME`
+ *
+ * Returns: (nullable) (transfer full): a new #GtkShortcutAction
+ *     or %NULL on error
+ */
 GtkShortcutAction *
 gtk_shortcut_action_parse_string (const char *string)
 {
diff --git a/gtk/gtkshortcuttrigger.c b/gtk/gtkshortcuttrigger.c
index 8be4bd3349..722a41fafd 100644
--- a/gtk/gtkshortcuttrigger.c
+++ b/gtk/gtkshortcuttrigger.c
@@ -118,10 +118,10 @@ gtk_shortcut_trigger_trigger (GtkShortcutTrigger *self,
  * The accepted strings are:
  *
  *   - `never`, for #GtkNeverTrigger
- *   - a string parsed by gtk_accelerator_parse(), for a #GtkKeyvalTrigger
- *   - underscore, followed by a single character, for #GtkMnemonicTrigger
+ *   - 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`
  *   - two valid trigger strings, separated by a `|` character, for a
- *     #GtkAlternativeTrigger
+ *     #GtkAlternativeTrigger: `<Control>q|<Control>w`
  *
  * Returns: (nullable) (transfer full): a new #GtkShortcutTrigger
  *   or %NULL on error