From 37f205ec1a0c5cc359fda442ca9e591b65e0900a Mon Sep 17 00:00:00 2001
From: Albert Y <76888457+filterpaper@users.noreply.github.com>
Date: Tue, 4 Apr 2023 07:06:33 +0800
Subject: [PATCH] Use table for debounce algorithm description (#20322)

---
 docs/feature_debounce_type.md | 52 +++++++++++++++--------------------
 1 file changed, 22 insertions(+), 30 deletions(-)

diff --git a/docs/feature_debounce_type.md b/docs/feature_debounce_type.md
index 9cd736a24a..8012037b6f 100644
--- a/docs/feature_debounce_type.md
+++ b/docs/feature_debounce_type.md
@@ -89,46 +89,38 @@ susceptible to noise, you must choose a debounce method that will also mitigate
    * Per-key and per-row algorithms consume more resources (in terms of performance,
      and ram usage), but fast typists might prefer them over global.
 
-## Debounce algorithms supported by QMK
+## Supported Debounce Algorithms
 
 QMK supports multiple debounce algorithms through its debounce API.
 
 ### Debounce selection
 
-| DEBOUNCE_TYPE    | Description                                          | What else is needed           |
-| -------------    | ---------------------------------------------------  | ----------------------------- |
-| Not defined      | Use the default algorithm, currently sym_defer_g     | Nothing                       |
-| custom           | Use your own debounce code                           | ```SRC += debounce.c``` add your own debounce.c and implement necessary functions |
-| Anything Else    | Use another algorithm from quantum/debounce/*        | Nothing                       |
-
-**Regarding split keyboards**:
-The debounce code is compatible with split keyboards.
-
-### Selecting an included debouncing method
-Keyboards may select one of the already implemented debounce methods, by adding to ```rules.mk``` the following line:
+Keyboards may select one of the core debounce methods by adding the following line into ```rules.mk```:
 ```
 DEBOUNCE_TYPE = <name of algorithm>
 ```
-Where name of algorithm is one of:
-* ```sym_defer_g``` - debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occurred, all input changes are pushed.
-  * This is the current default algorithm. This is the highest performance algorithm with lowest memory usage, and it's also noise-resistant.
-* ```sym_eager_pr``` - debouncing per row. On any state change, response is immediate, followed by locking the row ```DEBOUNCE``` milliseconds of no further input for that row.
-For use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive / low scan rate, and fingers usually only hit one row at a time. This could be
-appropriate for the ErgoDox models; the matrix is rotated 90°, and hence its "rows" are really columns, and each finger only hits a single "row" at a time in normal use.
-* ```sym_eager_pk``` - debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key
-* ```sym_defer_pr``` - debouncing per row. On any state change, a per-row timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that row, the entire row is pushed. Can improve responsiveness over `sym_defer_g` while being less susceptible than per-key debouncers to noise.
-* ```sym_defer_pk``` - debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key status change is pushed.
-* ```asym_eager_defer_pk``` - debouncing per key. On a key-down state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key. On a key-up state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key-up status change is pushed.
+Name of algorithm is one of:
 
-### A couple algorithms that could be implemented in the future:
-* ```sym_defer_pr```
-* ```sym_eager_g```
+| Algorithm                 | Description |
+| ------------------------- | ----------- |
+| ```sym_defer_g```         | Debouncing per keyboard. On any state change, a global timer is set. When ```DEBOUNCE``` milliseconds of no changes has occurred, all input changes are pushed. This is the highest performance algorithm with lowest memory usage and is noise-resistant. |
+| ```sym_defer_pr```        | Debouncing per row. On any state change, a per-row timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that row, the entire row is pushed. This can improve responsiveness over `sym_defer_g` while being less susceptible to noise than per-key algorithm. |
+| ```sym_defer_pk```        | Debouncing per key. On any state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key status change is pushed. |
+| ```sym_eager_pr```        | Debouncing per row. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that row. |
+| ```sym_eager_pk```        | Debouncing per key. On any state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key. |
+| ```asym_eager_defer_pk``` | Debouncing per key. On a key-down state change, response is immediate, followed by ```DEBOUNCE``` milliseconds of no further input for that key. On a key-up state change, a per-key timer is set. When ```DEBOUNCE``` milliseconds of no changes have occurred on that key, the key-up status change is pushed. |
+
+?> ```sym_defer_g``` is the default if ```DEBOUNCE_TYPE``` is undefined
+
+?> ```sym_eager_pr``` is suitable for use in keyboards where refreshing ```NUM_KEYS``` 8-bit counters is computationally expensive or has low scan rate while fingers usually hit one row at a time. This could be appropriate for the ErgoDox models where the matrix is rotated 90°. Hence its "rows" are really columns and each finger only hits a single "row" at a time with normal usage.
+
+### Implementing your own debouncing code
+
+You have the option to implement you own debouncing algorithm with the following steps:
 
-### Use your own debouncing code
-You have the option to implement you own debouncing algorithm. To do this:
 * Set ```DEBOUNCE_TYPE = custom``` in ```rules.mk```.
 * Add ```SRC += debounce.c``` in ```rules.mk```
-* Add your own ```debounce.c```. Look at current implementations in ```quantum/debounce``` for examples.
+* Implement your own ```debounce.c```. See ```quantum/debounce``` for examples.
 * Debouncing occurs after every raw matrix scan.
-* Use num_rows rather than MATRIX_ROWS, so that split keyboards are supported correctly.
-* If the algorithm might be applicable to other keyboards, please consider adding it to ```quantum/debounce```
+* Use num_rows instead of MATRIX_ROWS to support split keyboards correctly.
+* If your custom algorithm is applicable to other keyboards, please consider making a pull request.