From: Emmanuele Bassi <ebassi@gnome.org>
Date: Sat, 4 Sep 2021 17:56:08 +0000 (+0100)
Subject: Improve the gtk_accelerator_parse() docs
X-Git-Tag: archive/raspbian/4.4.1+ds1-2+rpi1^2~18^2^2~46
X-Git-Url: https://dgit.raspbian.org/?a=commitdiff_plain;h=07381e2b14ffa21b89f21119e0781f03425bb1bf;p=gtk4.git

Improve the gtk_accelerator_parse() docs

We need to escape the modifiers in angular brackets, or Markdown will
consider them as HTML tags.

We also should document the modifiers we're parsing.
---

diff --git a/gtk/gtkaccelgroup.c b/gtk/gtkaccelgroup.c
index fed9fe513e..3f0724d74f 100644
--- a/gtk/gtkaccelgroup.c
+++ b/gtk/gtkaccelgroup.c
@@ -484,15 +484,26 @@ out:
  *
  * Parses a string representing an accelerator.
  *
- * The format looks like “<Control>a” or “<Shift><Alt>F1”.
+ * The format looks like “`<Control>a`” or “`<Shift><Alt>F1`”.
  *
  * The parser is fairly liberal and allows lower or upper case, and also
- * abbreviations such as “<Ctl>” and “<Ctrl>”. Key names are parsed using
- * [func@Gdk.keyval_from_name]. For character keys the name is not the symbol,
- * but the lowercase name, e.g. one would use “<Ctrl>minus” instead of
- * “<Ctrl>-”.
+ * abbreviations such as “`<Ctl>`” and “`<Ctrl>`”.
  *
- * If the parse fails, @accelerator_key and @accelerator_mods will
+ * Key names are parsed using [func@Gdk.keyval_from_name]. For character keys
+ * the name is not the symbol, but the lowercase name, e.g. one would use
+ * “`<Ctrl>minus`” instead of “`<Ctrl>-`”.
+ *
+ * Modifiers are enclosed in angular brackets `<>`, and match the
+ * [enum@Gdk.ModifierType] mask:
+ *
+ * - `<Shift>` for `GDK_SHIFT_MASK`
+ * - `<Ctrl>` for `GDK_CONTROL_MASK`
+ * - `<Alt>` for `GDK_ALT_MASK`
+ * - `<Meta>` for `GDK_META_MASK`
+ * - `<Super>` for `GDK_SUPER_MASK`
+ * - `<Hyper>` for `GDK_HYPER_MASK`
+ *
+ * If the parse operation fails, @accelerator_key and @accelerator_mods will
  * be set to 0 (zero).
  */
 gboolean