From 9cf58ec8349769195e81b5100faf76f380c02757 Mon Sep 17 00:00:00 2001
From: jack <0x6A73@pm.me>
Date: Wed, 15 Feb 2023 15:40:47 -0700
Subject: [PATCH] Elaborate on keyboard level encoder functionality (#19839)

---
 docs/feature_encoders.md | 66 +++++++++++++---------------------------
 1 file changed, 21 insertions(+), 45 deletions(-)

diff --git a/docs/feature_encoders.md b/docs/feature_encoders.md
index cccdcbe4b31..1c521a4eff7 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,9 +104,27 @@ 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`:
 
+?> 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_kb(uint8_t index, bool clockwise) {
-    return encoder_update_user(index, 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);
+        } 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 true;
 }
 ```
 
@@ -131,49 +149,7 @@ bool encoder_update_user(uint8_t index, bool clockwise) {
 }
 ```
 
-!> 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:
-
-```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;
-    }
-    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