Keysym: Add apallingly bad API documentation for keysym <-> string

Signed-off-by: Daniel Stone <daniel@fooishbar.org>

diff --git a/include/X11/extensions/XKBcommon.h b/include/X11/extensions/XKBcommon.h
index 123ea8c..bb7bec3 100644 (file)
--- a/include/X11/extensions/XKBcommon.h
+++ b/include/X11/extensions/XKBcommon.h
@@ -141,9 +141,21 @@ XkbcCompileKeymapFromFile(FILE *inputFile, const char *mapName);
 extern XkbComponentListPtr
 XkbcListComponents(XkbComponentNamesPtr ptrns, int *maxMatch);
 
+/*
+ * Converts a keysym to a string; will return unknown Unicode codepoints
+ * as "Ua1b2", and other unknown keysyms as "0xabcd1234".
+ *
+ * The string returned may become invalidated after the next call to
+ * XkbcKeysymToString: if you need to preserve it, then you must
+ * duplicate it.
+ */
 extern char *
 XkbcKeysymToString(KeySym ks);
 
+/*
+ * See XkbcKeysymToString comments: this function will accept any string
+ * from that function.
+ */
 extern KeySym
 XkbcStringToKeysym(const char *s);