[gtk/ebassi/accel-parse-doc] Improve the gtk_accelerator_parse() docs

[Emmanuele Bassi <ebassi src gnome org>]

commit c3ca48b2492f9e1ce645973fbbc08fc19fee4064
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Sat Sep 4 18:56:08 2021 +0100

    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.

 gtk/gtkaccelgroup.c | 23 +++++++++++++++++------
 1 file changed, 17 insertions(+), 6 deletions(-)
---
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