[Core] get_keycode_string(): function to format keycodes as strings, for more readable debug logging.

builddefs/generic_features.mk

@@ -34,6 +34,7 @@ GENERIC_FEATURES = \
     DYNAMIC_TAPPING_TERM \
     GRAVE_ESC \
     HAPTIC \
+    KEYCODE_STRING \
     KEY_LOCK \
     KEY_OVERRIDE \
     LAYER_LOCK \

docs/faq_debug.md

@@ -77,6 +77,17 @@ KL: kc: 172, col: 2, row: 0, pressed: 1, time: 16303, int: 0, count: 0
 KL: kc: 172, col: 2, row: 0, pressed: 0, time: 16411, int: 0, count: 0
 ```
 
+### Which keycode is this keypress?
+
+Keycodes are logged in the example above as numerical codes, which may be difficult to interpret. For more readable logging, add `KEYCODE_STRING_ENABLE = yes` in your `rules.mk` and use `get_keycode_string(kc)`. For example:
+
+```c
+uprintf("kc: %s\n", get_keycode_string(keycode));
+```
+
+This logs the keycode as a human-readable string like "`LT(2,KC_D)`" rather than a numerical code like "`0x4207`." See the [Keycode String](unit_testing#keycode-string) section of the Unit Testing page for more information.
+
+
 ### How long did it take to scan for a keypress?
 
 When testing performance issues, it can be useful to know the frequency at which the switch matrix is being scanned. To enable logging for this scenario, add the following code to your keymaps `config.h`

docs/unit_testing.md

@@ -58,6 +58,35 @@ It's not yet possible to do a full integration test, where you would compile the
 
 In that model you would emulate the input, and expect a certain output from the emulated keyboard.
 
+# Keycode String {#keycode-string}
+
+It's much nicer to read keycodes as names like "`LT(2,KC_D)`" than numerical codes like "`0x4207`." To convert keycodes to human-readable strings, add `KEYCODE_STRING_ENABLE = yes` to the `rules.mk` file, then use the `get_keycode_string(kc)` function to convert a given 16-bit keycode to a string.
+
+```c
+const char *key_name = get_keycode_string(keycode);
+dprintf("kc: %s\n", key_name);
+```
+
+The stringified keycode may then be logged to console output with `dprintf()` or elsewhere.
+
+::: warning
+Use the result of `get_keycode_string()` immediately. Subsequent invocations reuse the same static buffer and overwrite the previous contents. 
+:::
+
+Many common QMK keycodes are recognized by `get_keycode_string()`, but not all. These include some common basic keycodes, layer switch keycodes, mod-taps, one-shot keycodes, tap dance keycodes, and Unicode keycodes. As a fallback, an unrecognized keycode is written as a hex number. 
+
+Optionally, `keycode_string_names_user` may be defined to add names for additional keycodes. For example, supposing keymap.c defines `MYMACRO1` and `MYMACRO2` as custom keycodes, the following adds their names:
+
+```c
+const keycode_string_name_t keycode_string_names_user[] = {
+    KEYCODE_STRING_NAME(MYMACRO1),
+    KEYCODE_STRING_NAME(MYMACRO2),
+    KEYCODE_STRING_NAMES_END // End of table sentinel.
+};
+```
+
+Similarly, `keycode_string_names_kb` may be defined to add names at the keyboard level.
+
 # Tracing Variables {#tracing-variables}
 
 Sometimes you might wonder why a variable gets changed and where, and this can be quite tricky to track down without having a debugger. It's of course possible to manually add print statements to track it, but you can also enable the variable trace feature. This works for both variables that are changed by the code, and when the variable is changed by some memory corruption.