Flesh out the quantum_keycodes documentation

1 files changed, 216 insertions, 141 deletions

diff --git a/docs/quantum_keycodes.md b/docs/quantum_keycodes.md
index 81eb647017..e9edad03ed 100644
--- a/docs/quantum_keycodes.md
+++ b/docs/quantum_keycodes.md
@@ -1,42 +1,50 @@
 # Quantum Keycodes
 
-Something important to realise with keycodes is that they are all numbers between `0x0` and `0xFFFF` - even though they may look like functions, words, or phrases, they are all shortcuts to some number. This allows us to define all of what they do in different places, and store keymaps in a relatively small place (arrays). If you try to "call" a keycode by placing it somewhere besides a keymap, it may compile, but it won't do anything useful. 
-
-All keycodes on this page have a value above `0xFF` (values less are considered the [basic keycodes](basic_keycodes.md)) and won't work with any of the mod/layer-tap keys listed at the bottom.
-
-* `SAFE_RANGE` is always the last keycode in the quantum list, and where custom lists can begin
-* `RESET` puts the keyboard into DFU mode for flashing
-* `DEBUG` toggles debug mode
-* Shortcuts for bootmagic options (work when bootmagic is off)
-    * `MAGIC_SWAP_CONTROL_CAPSLOCK`
-    * `MAGIC_CAPSLOCK_TO_CONTROL`
-    * `MAGIC_SWAP_LALT_LGUI`
-    * `MAGIC_SWAP_RALT_RGUI`
-    * `MAGIC_NO_GUI`
-    * `MAGIC_SWAP_GRAVE_ESC`
-    * `MAGIC_SWAP_BACKSLASH_BACKSPACE`
-    * `MAGIC_HOST_NKRO`
-    * `MAGIC_SWAP_ALT_GUI`/`AG_SWAP`
-    * `MAGIC_UNSWAP_CONTROL_CAPSLOCK`
-    * `MAGIC_UNCAPSLOCK_TO_CONTROL`
-    * `MAGIC_UNSWAP_LALT_LGUI`
-    * `MAGIC_UNSWAP_RALT_RGUI`
-    * `MAGIC_UNNO_GUI`
-    * `MAGIC_UNSWAP_GRAVE_ESC`
-    * `MAGIC_UNSWAP_BACKSLASH_BACKSPACE`
-    * `MAGIC_UNHOST_NKRO`
-    * `MAGIC_UNSWAP_ALT_GUI`/`AG_NORM`
-    * `MAGIC_TOGGLE_NKRO`
-* `KC_GESC`/`GRAVE_ESC` acts as escape when pressed normally but when pressed with a mod will send a `~`
-* `KC_LSPO` left shift when held, open paranthesis when tapped
-* `KC_RSPC` right shift when held, close paranthesis when tapped
-* `KC_LEAD` the leader key
-
-* `FUNC(n)`/`F(n)` to call `fn_action` n
-* `M(n)` to call macro n
-* `MACROTAP(n)` to macro-tap n idk FIXME
-
-## Audio
+All keycodes within quantum are numbers between `0x0000` and `0xFFFF`. Within your `keymap.c` it may look like you have functions and other special cases, but ultimately the C preprocessor will translate those into a single 4 byte integer. QMK has reserved `0x0000` through `0x00FF` for standard keycodes. These are keycodes such as `KC_A`, `KC_1`, and `KC_LCTL`, which are basic keys defined in the USB HID specification. 
+
+On this page we have documented keycodes between `0x00FF` and `0xFFFF` which are used to implement advanced quantum features. If you define your own custom keycodes they will be put into this range as well. Keycodes above `0x00FF` may not be used with any of the mod/layer-tap keys listed 
+
+# Quantum keycodes
+
+|Name|Description|
+|----|-----------|
+|`RESET`|Put the keyboard into DFU mode for flashing|
+|`DEBUG`|Toggles debug mode|
+|`KC_GESC`/`GRAVE_ESC`|Acts as escape when pressed normally but when pressed with Shift or GUI will send a `~`|
+|`KC_LSPO`|Left shift when held, open paranthesis when tapped|
+|`KC_RSPC`|Right shift when held, close paranthesis when tapped|
+|`KC_LEAD`|The [leader key](leader_key.md)|
+|`FUNC(n)`/`F(n)`|Call `fn_action(n)`|
+|`M(n)`|to call macro n|
+|`MACROTAP(n)`|to macro-tap n idk FIXME|
+
+# Bootmagic Keycodes
+
+Shortcuts for bootmagic options (these work even when bootmagic is off.)
+
+|Name|Description|
+|----|-----------|
+|`MAGIC_SWAP_CONTROL_CAPSLOCK`|Swap Capslock and Left Control|
+|`MAGIC_CAPSLOCK_TO_CONTROL`|Treat Capslock like a Control Key|
+|`MAGIC_SWAP_LALT_LGUI`|Swap the left Alt and GUI keys|
+|`MAGIC_SWAP_RALT_RGUI`|Swap the right Alt and GUI keys|
+|`MAGIC_NO_GUI`|Disable the GUI key|
+|`MAGIC_SWAP_GRAVE_ESC`|Swap the Grave and Esc key.|
+|`MAGIC_SWAP_BACKSLASH_BACKSPACE`|Swap backslack and backspace|
+|`MAGIC_HOST_NKRO`|Force NKRO on|
+|`MAGIC_SWAP_ALT_GUI`/`AG_SWAP`|Swap Alt and Gui on both sides|
+|`MAGIC_UNSWAP_CONTROL_CAPSLOCK`|Disable the Control/Capslock swap|
+|`MAGIC_UNCAPSLOCK_TO_CONTROL`|Disable treating Capslock like Control |
+|`MAGIC_UNSWAP_LALT_LGUI`|Disable Left Alt and GUI switching|
+|`MAGIC_UNSWAP_RALT_RGUI`|Disable Right Alt and GUI switching|
+|`MAGIC_UNNO_GUI`|Enable the GUI key |
+|`MAGIC_UNSWAP_GRAVE_ESC`|Disable the Grave/Esc swap |
+|`MAGIC_UNSWAP_BACKSLASH_BACKSPACE`|Disable the backslash/backspace swap|
+|`MAGIC_UNHOST_NKRO`|Force NKRO off|
+|`MAGIC_UNSWAP_ALT_GUI`/`AG_NORM`|Disable the Alt/GUI switching|
+|`MAGIC_TOGGLE_NKRO`|Turn NKRO on or off|
+
+# Audio
 
 ```c
 #ifdef AUDIO_ENABLE
@@ -126,7 +134,7 @@ MI_TRNSU, // transpose up
 
 MI_VEL_x 1-10
 MIDI_VELOCITY_MIN = MI_VEL_1,
-MIDI_VELOCITY_MAX = MI_VEL_10,
+MIDI_VELOCITY_MAX = MI_VEL_9,
 MI_VELD, // velocity down
 MI_VELU, // velocity up
 
@@ -149,126 +157,193 @@ MI_MODSD, // decrease modulation speed
 MI_MODSU, // increase modulation speed
 #endif // MIDI_ADVANCED
 
-## Backlight
+# Backlight
 
-* `BL_x` where x = 0-15
-* `BL_ON = BL_9`
-* `BL_OFF = BL_0`
-* `BL_DEC`
-* `BL_INC`
-* `BL_TOGG`
-* `BL_STEP`
+These keycodes control the backlight. Most keyboards use this for single color in-switch lighting.
 
-## RGB WS2818 LEDs
+|Name|Description|
+|----|-----------|
+|`BL_x`|Set a specific backlight level between 0-9|
+|`BL_ON`|An alias for `BL_9`|
+|`BL_OFF`|An alias for `BL_0`|
+|`BL_DEC`|Turn the backlight level down by 1|
+|`BL_INC`|Turn the backlight level up by 1|
+|`BL_TOGG`|Toggle the backlight on or off|
+|`BL_STEP`|Step through backlight levels, wrapping around to 0 when you reach the top.|
 
-* `RGB_TOG` toggle on/off
-* `RGB_MOD` cycle between modes
-* `RGB_HUI` hue increase
-* `RGB_HUD` hue decrease
-* `RGB_SAI` saturation increase
-* `RGB_SAD` saturation decrease
-* `RGB_VAI` value increase
-* `RGB_VAD` value decrease
+# RGBLIGHT WS2818 LEDs
+
+This controls the `RGBLIGHT` functionality. Most keyboards use WS2812 (and compatible) LEDs for underlight or case lighting.
+
+|Name|Description|
+|----|-----------|
+|`RGB_TOG`|toggle on/off|
+|`RGB_MOD`|cycle through modes|
+|`RGB_HUI`|hue increase|
+|`RGB_HUD`|hue decrease|
+|`RGB_SAI`|saturation increase|
+|`RGB_SAD`|saturation decrease|
+|`RGB_VAI`|value increase|
+|`RGB_VAD`|value decrease|
 
 ## Thermal Printer (experimental)
 
-* `PRINT_ON`
-* `PRINT_OFF`
+|Name|Description|
+|----|-----------|
+|`PRINT_ON`|Start printing everything the user types|
+|`PRINT_OFF`|Stop printing everything the user types|
 
 ## Keyboard output selection
 
-* `OUT_AUTO` auto mode
-* `OUT_USB` usb only
-* `OUT_BT` bluetooth (when `BLUETOOTH_ENABLE`)
+This is used when multiple keyboard outputs can be selected. Currently this only allows for switching between USB and Bluetooth on keyboards that support both.
+
+|Name|Description|
+|----|-----------|
+|`OUT_AUTO`|auto mode|
+|`OUT_USB`|usb only|
+|`OUT_BT`|bluetooth (when `BLUETOOTH_ENABLE`)|
+
+# Modifiers
 
-## Modifiers
+These are special keycodes that simulate pressing several modifiers at once.
 
-* `KC_HYPR` LCTL + LSFT + LALT + LGUI - `MOD_HYPR` is the bit version
-* `KC_MEH` LCTL + LSFT + LALT - `MOD_MEH` is the bit version
+|Name|Description|
+|----|-----------|
+|`KC_HYPR`|Hold down LCTL + LSFT + LALT + LGUI|
+|`KC_MEH`|Hold down LCTL + LSFT + LALT|
 
-### Modifiers with keys
+/* FIXME: Should we have these in QMK too?
+ * |`KC_LCAG`|`LCTL` + `LALT` + `LGUI`|
+ * |`KC_ALTG`|`RCTL` + `RALT`|
+ * |`KC_SCMD`/`KC_SWIN`|`LGUI` + `LSFT`|
+ * |`KC_LCA`|`LCTL` + `LALT`|
+ */
 
-* `LCTL(kc)` LCTL + kc
-* `LSFT(kc)`/`S(kc)` LSFT + kc
-* `LALT(kc)` LALT + kc
-* `LGUI(kc)` LGUI + kc
-* `RCTL(kc)` RCTL + kc
-* `RSFT(kc)` RSFT + kc
-* `RALT(kc)` RALT + kc
-* `RGUI(kc)` RGUI + kc
+## Modifiers with keys
 
-* `HYPR(kc)` LCTL + LSFT + LALT + LGUI + kc
-* `MEH(kc)`  LCTL + LSFT + LALT + kc 
-* `LCAG(kc)` LCTL + LALT + LGUI + kc
-* `ALTG(kc)` RCTL + RALT + kc
-* `SCMD(kc)`/`SWIN(kc)` LGUI + LSFT + kc
-* `LCA(kc)` LCTL + LALT + kc
+|Name|Description|
+|----|-----------|
+|`LCTL(kc)`|`LCTL` + `kc`|
+|`LSFT(kc)`/`S(kc)`|`LSFT` + `kc`|
+|`LALT(kc)`|`LALT` + `kc`|
+|`LGUI(kc)`|`LGUI` + `kc`|
+|`RCTL(kc)`|`RCTL` + `kc`|
+|`RSFT(kc)`|`RSFT` + `kc`|
+|`RALT(kc)`|`RALT` + `kc`|
+|`RGUI(kc)`|`RGUI` + `kc`|
+|`HYPR(kc)`|`LCTL` + `LSFT` + `LALT` + `LGUI` + `kc`|
+|`MEH(kc)`|`LCTL` + `LSFT` + `LALT` + `kc`|
+|`LCAG(kc)`|`LCTL` + `LALT` + `LGUI` + `kc`|
+|`ALTG(kc)`|`RCTL` + `RALT` + `kc`|
+|`SCMD(kc)`/`SWIN(kc)`|`LGUI` + `LSFT` + `kc`|
+|`LCA(kc)`|`LCTL` + `LALT` + `kc`|
 
-* `OSM(mod)` use mod for one keypress - use mod bits with this
+## One Shot Keys
 
-> Mod bits are the 4-letter part of the keycode prefixed with `MOD_`, e.g. `MOD_LCTL`
+Most modifiers work by being held down while you push another key. You can use `OSM()` to setup a "One Shot" modifier. When you tap a one shot mod it will remain is a pressed state until you press another key. 
 
-### Mod-tap keys
+To specify a your modifier you need to pass the `MOD` form of the key. For example, if you want to setup a One Shot Control you would use `OSM(MOD_LCTL)`.
+
+|Name|Description|
+|----|-----------|
+|`OSM(mod)`|use mod for one keypress|
+|`OSL(layer)`|switch to layer for one keypress|
+
+## Mod-tap keys
 
 These keycodes will press the mod(s) when held, and the key when tapped. They only work with [basic keycodes](basic_keycodes.md). 
 
-* `CTL_T(kc)`/`LCTL_T(kc)` LCTL when held, kc when tapped
-* `RCTL_T(kc)` RCTL when held, kc when tapped
-
-* `SFT_T(kc)`/`LSFT_T(kc)` LSFT when held, kc when tapped
-* `RSFT_T(kc)` RSFT when held, kc when tapped
-
-* `ALT_T(kc)`/`LALT_T(kc)` LALT when held, kc when tapped
-* `RALT_T(kc)`/`ALGR_T(kc)` RALT when held, kc when tapped
-
-* `GUI_T(kc)`/`LGUI_T(kc)` LGUI when held, kc when tapped
-* `RGUI_T(kc)` RGUI when held, kc when tapped
-
-* `C_S_T(kc)` LCTL + LSFT when held, kc when tapped
-* `MEH_T(kc)` LCTL + LSFT + LALT when held, kc when tapped
-* `LCAG_T(kc)` LCTL + LALT + LGUI when held, kc when tapped
-* `RCAG_T(kc)` RCTL + RALT + RGUI when held, kc when tapped
-* `ALL_T(kc)` LCTL + LSFT + LALT + LGUI when held, kc tapped [more info](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)
-* `SCMD_T(kc)`/`SWIN_T(kc)` LGUI + LSFT when held, kc when tapped
-* `LCA_T(kc)` LCTL + LALT when held, kc when tapped
-
-## Shifted symbols
-
-It's important to remember that all of the keycodes also send a left shift - this may cause unintended actions if unaccounted for. The 4-letter code is preferred in most situations.
-
-* `KC_TILD`/`KC_TILDE` tilde `~`
-* `KC_EXLM`/`KC_EXCLAIM` exclamation mark `!`
-* `KC_AT` at sign `@`
-* `KC_HASH` hash sign `#`
-* `KC_DLR`/`KC_DOLLAR` dollar sign `$`
-* `KC_PERC`/`KC_PERCENT` percent sign `%`
-* `KC_CIRC`/`KC_CIRCUMFLEX` circumflex `^`
-* `KC_AMPR`/`KC_AMPERSAND` ampersand `&`
-* `KC_ASTR`/`KC_ASTERISK` asterisk `*`
-* `KC_LPRN`/`KC_LEFT_PAREN` left parenthesis `(`
-* `KC_RPRN`/`KC_RIGHT_PAREN` right parenthesis `)`
-* `KC_UNDS`/`KC_UNDERSCORE` underscore `_`
-* `KC_PLUS` plus sign `+`
-* `KC_LCBR`/`KC_LEFT_CURLY_BRACE` left curly brace `{`
-* `KC_RCBR`/`KC_RIGHT_CURLY_BRACE` right curly brace `}`
-* `KC_LT`/`KC_LABK`/`KC_LEFT_ANGLE_BRACKET` left angle bracket `<`
-* `KC_GT`/`KC_RABK`/`KC_RIGHT_ANGLE_BRACKET` right angle bracket `>`
-* `KC_COLN`/`KC_COLON` colon `:`
-* `KC_PIPE` pipe `|`
-* `KC_QUES`/`KC_QUESTION` question mark `?`
-* `KC_DQT`/`KC_DOUBLE_QUOTE`/`KC_DQUO` double quote `"`
-
-## Layer adjustments
-
-* `LT(layer, kc)` turn on layer (0-15) when held, kc ([basic keycodes](basic_keycodes.md)) when tapped
-* `TO(layer)` turn on layer when depressed
-* `MO(layer)` momentarily turn on layer when depressed (requires `KC_TRNS` on destination layer)
-* `DF(layer)` sets the base (default) layer
-* `TG(layer)` toggle layer on/off
-* `OSL(layer)` switch to layer for one keycode
-* `TT(layer)` tap toggle? idk FIXME
-
-## Unicode
-
-* `UNICODE(n)`/`UC(n)` if `UNICODE_ENABLE`, this will send characters up to `0x7FFF`
-* `X(n)` if `UNICODEMAP_ENABLE`, also sends unicode via a different method
\ No newline at end of file
+|Name|Description|
+|----|-----------|
+|`CTL_T(kc)`/`LCTL_T(kc)`|`LCTL` when held, `kc` when tapped|
+|`RCTL_T(kc)`|`RCTL` when held, `kc` when tapped|
+|`SFT_T(kc)`/`LSFT_T(kc)`|`LSFT` when held, `kc` when tapped|
+|`RSFT_T(kc)`|`RSFT` when held, `kc` when tapped|
+|`ALT_T(kc)`/`LALT_T(kc)`|`LALT` when held, `kc` when tapped|
+|`RALT_T(kc)`/`ALGR_T(kc)`|`RALT` when held, `kc` when tapped|
+|`GUI_T(kc)`/`LGUI_T(kc)`|`LGUI` when held, `kc` when tapped|
+|`RGUI_T(kc)`|`RGUI` when held, `kc` when tapped|
+|`C_S_T(kc)`|`LCTL` + `LSFT` when held, `kc` when tapped|
+|`MEH_T(kc)`|`LCTL` + `LSFT` + `LALT` when held, `kc` when tapped|
+|`LCAG_T(kc)`|`LCTL` + `LALT` + `LGUI` when held, `kc` when tapped|
+|`RCAG_T(kc)`|`RCTL` + `RALT` + `RGUI` when held, `kc` when tapped|
+|`ALL_T(kc)`|`LCTL` + `LSFT` + `LALT` + `LGUI` when held, `kc` when tapped [more info](http://brettterpstra.com/2012/12/08/a-useful-caps-lock-key/)|
+|`SCMD_T(kc)`/`SWIN_T(kc)`|`LGUI` + `LSFT` when held, `kc` when tapped|
+|`LCA_T(kc)`|`LCTL` + `LALT` when held, `kc` when tapped|
+
+# US ANSI Shifted symbols
+
+These keycodes correspond to characters that are "shifted" on a standard US ANSI keyboards. They do not have dedicated keycodes but are instead typed by holding down shift and then sending a keycode. 
+
+It's important to remember that all of these keycodes send a left shift - this may cause unintended actions if unaccounted for. The short code is preferred in most situations.
+
+|Short Name|Long Name|Description|
+|----------|---------|-----------|
+|`KC_TILD`|`KC_TILDE`|tilde `~`|
+|`KC_EXLM`|`KC_EXCLAIM`|exclamation mark `!`|
+|`KC_AT`||at sign `@`|
+|`KC_HASH`||hash sign `#`|
+|`KC_DLR`|`KC_DOLLAR`|dollar sign `$`|
+|`KC_PERC`|`KC_PERCENT`|percent sign `%`|
+|`KC_CIRC`|`KC_CIRCUMFLEX`|circumflex `^`|
+|`KC_AMPR`|`KC_AMPERSAND`|ampersand `&`|
+|`KC_ASTR`|`KC_ASTERISK`|asterisk `*`|
+|`KC_LPRN`|`KC_LEFT_PAREN`|left parenthesis `(`|
+|`KC_RPRN`|`KC_RIGHT_PAREN`|right parenthesis `)`|
+|`KC_UNDS`|`KC_UNDERSCORE`|underscore `_`|
+|`KC_PLUS`||plus sign `+`|
+|`KC_LCBR`|`KC_LEFT_CURLY_BRACE`|left curly brace `{`|
+|`KC_RCBR`|`KC_RIGHT_CURLY_BRACE`|right curly brace `}`|
+|`KC_LT`/`KC_LABK`|`KC_LEFT_ANGLE_BRACKET`|left angle bracket `<`|
+|`KC_GT`/`KC_RABK`|`KC_RIGHT_ANGLE_BRACKET`|right angle bracket `>`|
+|`KC_COLN`|`KC_COLON`|colon `:`|
+|`KC_PIPE`||pipe `\|`|
+|`KC_QUES`|`KC_QUESTION`|question mark `?`|
+|`KC_DQT`/`KC_DQUO`|`KC_DOUBLE_QUOTE`|double quote `"`|
+
+# Layer Changes
+
+These are keycodes that can be used to change the current layer.
+
+|Name|Description|
+|----|-----------|
+|`LT(layer, kc)`|turn on layer (0-15) when held, kc ([basic keycodes](basic_keycodes.md)) when tapped|
+|`TO(layer)`|turn on layer when depressed|
+|`MO(layer)`|momentarily turn on layer when depressed (requires `KC_TRNS` on destination layer)|
+|`DF(layer)`|sets the base (default) layer|
+|`TG(layer)`|toggle layer on/off|
+|`TT(layer)`|tap toggle? idk FIXME|
+|`OSL(layer)`|switch to layer for one keycode|
+
+# Unicode
+
+These keycodes can be used in conjuction with the [Unicode](unicode_and_additional_language_support.md) support.
+
+|`UNICODE(n)`/`UC(n)`|if `UNICODE_ENABLE`, this will send characters up to `0x7FFF`|
+|`X(n)`|if `UNICODEMAP_ENABLE`, also sends unicode via a different method|
+
+# `SAFE_RANGE`, or safely defining custom keycodes
+
+Sometimes you want to define your own custom keycodes to make your keymap easier to read. QMK provides `SAFE_RANGE` to help you do that. `SAFE_RANGE` is the first available keycode in the `0x0000`-`0xFFFF` range and you can use it when creating your own custom keycode enum:
+
+```
+enum my_keycodes {
+  FOO = SAFE_RANGE,
+  BAR
+};
+```
+
+You can then use `process_record_user()` to do something with your keycode:
+
+```
+bool process_record_user(uint16_t keycode, keyrecord_t *record) {
+  switch (keycode) {
+    case FOO:
+      // Do something here
+      break;
+    case BAR:
+      // Do something here
+      break;
+  }
+}
+```