Improve consistency in UNICODEMAP code and docs, update docs/understanding_qmk (#4774)

* Remove unused UNICODE(n) macro, update docs

* Add note about max length of unicode_map to docs

* QK_UNICODE_MAP → QK_UNICODEMAP

* Refactor process_unicode_map

* process_unicode_map → process_unicodemap

This is done for consistency: UNICODEMAP is the method (hence UNICODEMAP_ENABLE, process_unicodemap), whereas unicode_map is the mapping table itself.

* Update references and ordering in docs/understanding_qmk

* Add additional note to docs/understanding_qmk

* &unicode_map[index] → unicode_map + index

This avoids the issue of the compiler sometimes complaining about the array index being out of range

* Update docs/getting_started_make_guide

* Update method sections in docs/feature_unicode

4 files changed, 25 insertions, 29 deletions

diff --git a/quantum/process_keycode/process_unicode_common.c b/quantum/process_keycode/process_unicode_common.c
index 3286f45b5d..b64feb7003 100644
--- a/quantum/process_keycode/process_unicode_common.c
+++ b/quantum/process_keycode/process_unicode_common.c
@@ -216,7 +216,7 @@ bool process_unicode_common(uint16_t keycode, keyrecord_t *record) {
 #if   defined(UNICODE_ENABLE)
   return process_unicode(keycode, record);
 #elif defined(UNICODEMAP_ENABLE)
-  return process_unicode_map(keycode, record);
+  return process_unicodemap(keycode, record);
 #elif defined(UCIS_ENABLE)
   return process_ucis(keycode, record);
 #else
diff --git a/quantum/process_keycode/process_unicodemap.c b/quantum/process_keycode/process_unicodemap.c
index 75f35112b1..cee9acb5fc 100644
--- a/quantum/process_keycode/process_unicodemap.c
+++ b/quantum/process_keycode/process_unicodemap.c
@@ -18,8 +18,7 @@
 #include "process_unicode_common.h"
 
 __attribute__((weak))
-const uint32_t PROGMEM unicode_map[] = {
-};
+const uint32_t PROGMEM unicode_map[] = {};
 
 void register_hex32(uint32_t hex) {
   bool onzerostart = true;
@@ -42,26 +41,26 @@ void register_hex32(uint32_t hex) {
 }
 
 __attribute__((weak))
-void unicode_map_input_error() {}
+void unicodemap_input_error() {}
 
-bool process_unicode_map(uint16_t keycode, keyrecord_t *record) {
-  uint8_t input_mode = get_unicode_input_mode();
-  if ((keycode & QK_UNICODE_MAP) == QK_UNICODE_MAP && record->event.pressed) {
-    const uint32_t* map = unicode_map;
-    uint16_t index = keycode - QK_UNICODE_MAP;
-    uint32_t code = pgm_read_dword(&map[index]);
-    if (code > 0xFFFF && code <= 0x10ffff && input_mode == UC_OSX) {
+bool process_unicodemap(uint16_t keycode, keyrecord_t *record) {
+  if ((keycode & QK_UNICODEMAP) == QK_UNICODEMAP && record->event.pressed) {
+    uint16_t index = keycode - QK_UNICODEMAP;
+    uint32_t code = pgm_read_dword(unicode_map + index);
+    uint8_t input_mode = get_unicode_input_mode();
+
+    if (code > 0xFFFF && code <= 0x10FFFF && input_mode == UC_OSX) {
       // Convert to UTF-16 surrogate pair
       code -= 0x10000;
-      uint32_t lo = code & 0x3ff;
-      uint32_t hi = (code & 0xffc00) >> 10;
+      uint32_t lo = code & 0x3FF, hi = (code & 0xFFC00) >> 10;
+
       unicode_input_start();
-      register_hex32(hi + 0xd800);
-      register_hex32(lo + 0xdc00);
+      register_hex32(hi + 0xD800);
+      register_hex32(lo + 0xDC00);
       unicode_input_finish();
-    } else if ((code > 0x10ffff && input_mode == UC_OSX) || (code > 0xFFFFF && input_mode == UC_LNX)) {
-      // when character is out of range supported by the OS
-      unicode_map_input_error();
+    } else if ((code > 0x10FFFF && input_mode == UC_OSX) || (code > 0xFFFFF && input_mode == UC_LNX)) {
+      // Character is out of range supported by the OS
+      unicodemap_input_error();
     } else {
       unicode_input_start();
       register_hex32(code);
diff --git a/quantum/process_keycode/process_unicodemap.h b/quantum/process_keycode/process_unicodemap.h
index f6d64bb86b..5764697f84 100644
--- a/quantum/process_keycode/process_unicodemap.h
+++ b/quantum/process_keycode/process_unicodemap.h
@@ -19,5 +19,5 @@
 #include "quantum.h"
 #include "process_unicode_common.h"
 
-void unicode_map_input_error(void);
-bool process_unicode_map(uint16_t keycode, keyrecord_t *record);
+void unicodemap_input_error(void);
+bool process_unicodemap(uint16_t keycode, keyrecord_t *record);
diff --git a/quantum/quantum_keycodes.h b/quantum/quantum_keycodes.h
index 2b309f4d52..ccf5371f0e 100644
--- a/quantum/quantum_keycodes.h
+++ b/quantum/quantum_keycodes.h
@@ -86,8 +86,8 @@ enum quantum_keycodes {
     QK_UNICODE_MAX        = 0xFFFF,
 #endif
 #ifdef UNICODEMAP_ENABLE
-    QK_UNICODE_MAP        = 0x8000,
-    QK_UNICODE_MAP_MAX    = 0x83FF,
+    QK_UNICODEMAP         = 0x8000,
+    QK_UNICODEMAP_MAX     = 0x83FF,
 #endif
 
     // Loose keycodes - to be used directly
@@ -679,15 +679,12 @@ enum quantum_keycodes {
 #define KC_MEH  MEH(KC_NO)
 
 #ifdef UNICODE_ENABLE
-    // For sending unicode codes.
-    // You may not send codes over 7FFF -- this supports most of UTF8.
-    // To have a key that sends out Œ, go UC(0x0152)
-    #define UNICODE(n) (QK_UNICODE | (n))
-    #define UC(n) UNICODE(n)
+  // Allows Unicode input up to 0x7FFF
+  #define UC(c) (QK_UNICODE | (c))
 #endif
-
 #ifdef UNICODEMAP_ENABLE
-    #define X(n) (QK_UNICODE_MAP | (n))
+  // Allows Unicode input up to 0x10FFFF, requires unicode_map
+  #define X(i) (QK_UNICODEMAP | (i))
 #endif
 
 #define UC_MOD  UNICODE_MODE_FORWARD