[Jack & Erez] Comments + tiny updates and cleanup

1 files changed, 27 insertions, 2 deletions

diff --git a/quantum/keymap_common.h b/quantum/keymap_common.h
index 30ef9365ad..b1df4eb0f6 100644
--- a/quantum/keymap_common.h
+++ b/quantum/keymap_common.h
@@ -72,33 +72,51 @@ extern const uint16_t fn_actions[];
 #define RGUI(kc) kc | 0x1800
 
 // Aliases for shifted symbols
+// Each key has a 4-letter code, and some have longer aliases too.
+// While the long aliases are descriptive, the 4-letter codes
+// make for nicer grid layouts (everything lines up), and are
+// the preferred style for Quantum.
 #define KC_TILD LSFT(KC_GRV)    // ~
 #define KC_TILDE    KC_TILD
+
 #define KC_EXLM LSFT(KC_1)      // !
 #define KC_EXCLAIM  KC_EXLM
+
 #define KC_AT   LSFT(KC_2)      // @
 #define KC_HASH LSFT(KC_3)      // #
+
 #define KC_DLR  LSFT(KC_4)      // $
 #define KC_DOLLAR   KC_DLR
+
 #define KC_PERC LSFT(KC_5)      // %
 #define KC_PERCENT  KC_PERC
+
 #define KC_CIRC LSFT(KC_6)      // ^
 #define KC_CIRCUMFLEX   KC_CIRC
+
 #define KC_AMPR LSFT(KC_7)      // &
 #define KC_AMPERSAND    KC_AMPR
+
 #define KC_ASTR LSFT(KC_8)      // *
 #define KC_ASTERISK KC_ASTR
+
 #define KC_LPRN LSFT(KC_9)      // (
 #define KC_LEFT_PAREN   KC_LPRN
+
 #define KC_RPRN LSFT(KC_0)      // )
 #define KC_RIGHT_PAREN  KC_RPRN
+
 #define KC_UNDS LSFT(KC_MINS)   // _
 #define KC_UNDERSCORE   KC_UNDS
+
 #define KC_PLUS LSFT(KC_EQL)    // +
+
 #define KC_LCBR LSFT(KC_LBRC)   // {
 #define KC_LEFT_CURLY_BRACE KC_LCBR
+
 #define KC_RCBR LSFT(KC_RBRC)   // }
 #define KC_RIGHT_CURLY_BRACE    KC_RCBR
+
 #define KC_PIPE LSFT(KC_SLSH)   // |
 
 // Alias for function layers than expand past FN31
@@ -112,6 +130,9 @@ extern const uint16_t fn_actions[];
 
 #define MACRODOWN(...) (record->event.pressed ? MACRO(__VA_ARGS__) : MACRO_NONE)
 
+// These affect the backlight (if your keyboard has one).
+// We don't need to comment them out if your keyboard doesn't have a backlight,
+// since they don't take up any space.
 #define BL_ON 0x4009
 #define BL_OFF 0x4000
 #define BL_0 0x4000
@@ -142,7 +163,7 @@ extern const uint16_t fn_actions[];
 // when:
 // ON_PRESS    = 1
 // ON_RELEASE  = 2
-// ON_BOTH     = 3
+// Unless you have a good reason not to do so, prefer  ON_PRESS (1) as your default.
 #define TO(layer, when) (layer | 0x5100 | (when << 0x4))
 
 // Momentary switch layer - 256 layer max
@@ -153,7 +174,11 @@ extern const uint16_t fn_actions[];
 
 #define MIDI(n) (n | 0x6000)
 
-#define UNI(n) (n | 0x8000)
+// For sending unicode codes.
+// You may not send codes over 1FFF -- this supports most of UTF8.
+// To have a key that sends out Œ, go UC(0x0152)
+#define UNICODE(n) (n | 0x8000)
+#define UC(n) UNICODE(n)
 
 
 #endif