doc: some notes about key names and aliases

Signed-off-by: Ran Benita <ran234@gmail.com>

2 files changed, 10 insertions, 0 deletions

diff --git a/doc/compat.md b/doc/compat.md
index 63a45e7..14c57c5 100644
--- a/doc/compat.md
+++ b/doc/compat.md
@@ -44,6 +44,7 @@ Notable additions:
 - multiple keysyms per level
   + this requires incompatible dataset changes, such that X11 would
     not be able to parse these
+- key names (e.g. `<AE11>`) can be longer than 4 characters.
 
 ## Compose support
 
diff --git a/xkbcommon/xkbcommon.h b/xkbcommon/xkbcommon.h
index 9d79bf2..a3c5fce 100644
--- a/xkbcommon/xkbcommon.h
+++ b/xkbcommon/xkbcommon.h
@@ -152,6 +152,10 @@ struct xkb_state;
  * underlying input system.  For example, with an X11-compatible keymap
  * and Linux evdev scan codes (see linux/input.h), a fixed offset is used:
  *
+ * The keymap defines a canonical name for each key, plus possible aliases.
+ * Historically, the XKB protocol restricts these names to at most 4 (ASCII)
+ * characters, but this library does not share this limit.
+ *
  * @code
  * xkb_keycode_t keycode_A = KEY_A + 8;
  * @endcode
@@ -943,6 +947,9 @@ xkb_keymap_key_for_each(struct xkb_keymap *keymap, xkb_keymap_key_iter_t iter,
 /**
  * Find the name of the key with the given keycode.
  *
+ * This function always returns the canonical name of the key (see
+ * description in xkb_keycode_t).
+ *
  * @returns The key name. If no key with this keycode exists,
  * returns NULL.
  *
@@ -956,6 +963,8 @@ xkb_keymap_key_get_name(struct xkb_keymap *keymap, xkb_keycode_t key);
 /**
  * Find the keycode of the key with the given name.
  *
+ * The name can be either a canonical name or an alias.
+ *
  * @returns The keycode. If no key with this name exists,
  * returns XKB_KEYCODE_INVALID.
  *