Elaborate on keyboard level encoder functionality (#19839)

1 files changed, 21 insertions, 45 deletions

diff --git a/docs/feature_encoders.md b/docs/feature_encoders.md
index cccdcbe4b3..1c521a4eff 100644
--- a/docs/feature_encoders.md
+++ b/docs/feature_encoders.md
@@ -1,6 +1,6 @@
 # Encoders
 
-Basic encoders are supported by adding this to your `rules.mk`:
+Basic (EC11 compatible) encoders are supported by adding this to your `rules.mk`:
 
 ```make
 ENCODER_ENABLE = yes
@@ -104,16 +104,13 @@ Using encoder mapping pumps events through the normal QMK keycode processing pip
 
 When not using `ENCODER_MAP_ENABLE = yes`, the callback functions can be inserted into your `<keyboard>.c`:
 
-```c
-bool encoder_update_kb(uint8_t index, bool clockwise) {
-    return encoder_update_user(index, clockwise);
-}
-```
-
-or `keymap.c`:
+?> Those who are adding new keyboard support where encoders are enabled at the keyboard level should include basic encoder functionality at the keyboard level (`<keyboard>.c`) using the `encoder_update_kb()` function, that way it works for QMK Configuator users and exists in general.
 
 ```c
-bool encoder_update_user(uint8_t index, bool clockwise) {
+bool encoder_update_kb(uint8_t index, bool clockwise) {
+    if (!encoder_update_user(index, clockwise)) {
+      return false; /* Don't process further events if user function exists and returns false */
+    }
     if (index == 0) { /* First encoder */
         if (clockwise) {
             tap_code_delay(KC_VOLU, 10);
@@ -127,53 +124,32 @@ bool encoder_update_user(uint8_t index, bool clockwise) {
             rgb_matrix_decrease_hue();
         }
     }
-    return false;
+    return true;
 }
 ```
 
-!> If you return `true`, it will allow the keyboard level code to run as well. Returning `false` will override the keyboard level code, depending on how the keyboard function is set up.
-
-Layer conditions can also be used with the callback function like the following:
+or `keymap.c`:
 
 ```c
 bool encoder_update_user(uint8_t index, bool clockwise) {
-    switch(get_highest_layer(layer_state|default_layer_state)) {
-        case 0:
-            if (index == 0) {
-                if (clockwise) {
-                    tap_code(KC_PGDN);
-                } else {
-                    tap_code(KC_PGUP);
-                }
-            } else if (index == 1) {
-                if (clockwise) {
-                    rgb_matrix_increase_speed();
-                } else {
-                    rgb_matrix_decrease_speed();
-                }
-            }
-            break;
-        case 1:
-            if (index == 0) {
-                if (clockwise) {
-                    tap_code(KC_WH_D);
-                } else {
-                    tap_code(KC_WH_U);
-                }
-            } else if (index == 1) {
-                if (clockwise) {
-                    tap_code_delay(KC_VOLU, 10);
-                } else {
-                    tap_code_delay(KC_VOLD, 10);
-                }
-            }
-            break;
+    if (index == 0) { /* First encoder */
+        if (clockwise) {
+            tap_code_delay(KC_VOLU, 10);
+        } else {
+            tap_code_delay(KC_VOLD, 10);
+        }
+    } else if (index == 1) { /* Second encoder */
+        if (clockwise) {
+            rgb_matrix_increase_hue();
+        } else {
+            rgb_matrix_decrease_hue();
+        }
     }
     return false;
 }
 ```
 
-?> Media and mouse countrol keycodes such as `KC_VOLU` and `KC_WH_D` requires `EXTRAKEY_ENABLE = yes` and `MOUSEKEY_ENABLE = yes` respectively in user's `rules.mk` if they are not enabled as default on keyboard level configuration.
+!> If you return `true` in the keymap level `_user` function, it will allow the keyboard level encoder code to run on top of your own. Returning `false` will override the keyboard level function, if setup correctly. This is generally the safest option to avoid confusion.
 
 ## Hardware