Programmable Button API refactor and improve docs (#18641)

5 files changed, 89 insertions, 25 deletions

diff --git a/quantum/action.c b/quantum/action.c
index 78322e4a83..abf9834d2f 100644
--- a/quantum/action.c
+++ b/quantum/action.c
@@ -1081,7 +1081,6 @@ void clear_keyboard_but_mods_and_keys() {
 #endif
 #ifdef PROGRAMMABLE_BUTTON_ENABLE
     programmable_button_clear();
-    programmable_button_send();
 #endif
 }
 
diff --git a/quantum/keyboard.c b/quantum/keyboard.c
index 280532a5fd..eb5e4b583a 100644
--- a/quantum/keyboard.c
+++ b/quantum/keyboard.c
@@ -66,9 +66,6 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 #ifdef JOYSTICK_ENABLE
 #    include "process_joystick.h"
 #endif
-#ifdef PROGRAMMABLE_BUTTON_ENABLE
-#    include "programmable_button.h"
-#endif
 #ifdef HD44780_ENABLE
 #    include "hd44780.h"
 #endif
@@ -669,10 +666,6 @@ void keyboard_task(void) {
     digitizer_task();
 #endif
 
-#ifdef PROGRAMMABLE_BUTTON_ENABLE
-    programmable_button_send();
-#endif
-
 #ifdef BLUETOOTH_ENABLE
     bluetooth_task();
 #endif
diff --git a/quantum/process_keycode/process_programmable_button.c b/quantum/process_keycode/process_programmable_button.c
index c6e77faacc..6379698848 100644
--- a/quantum/process_keycode/process_programmable_button.c
+++ b/quantum/process_keycode/process_programmable_button.c
@@ -22,9 +22,9 @@ bool process_programmable_button(uint16_t keycode, keyrecord_t *record) {
     if (keycode >= PROGRAMMABLE_BUTTON_MIN && keycode <= PROGRAMMABLE_BUTTON_MAX) {
         uint8_t button = keycode - PROGRAMMABLE_BUTTON_MIN + 1;
         if (record->event.pressed) {
-            programmable_button_on(button);
+            programmable_button_register(button);
         } else {
-            programmable_button_off(button);
+            programmable_button_unregister(button);
         }
     }
     return true;
diff --git a/quantum/programmable_button.c b/quantum/programmable_button.c
index a3ef42d82b..b6c9ad3189 100644
--- a/quantum/programmable_button.c
+++ b/quantum/programmable_button.c
@@ -24,27 +24,38 @@ static uint32_t programmable_button_report = 0;
 
 void programmable_button_clear(void) {
     programmable_button_report = 0;
+    programmable_button_flush();
 }
 
-void programmable_button_send(void) {
-    host_programmable_button_send(programmable_button_report);
-}
-
-void programmable_button_on(uint8_t index) {
+void programmable_button_add(uint8_t index) {
     programmable_button_report |= REPORT_BIT(index);
 }
 
-void programmable_button_off(uint8_t index) {
+void programmable_button_remove(uint8_t index) {
     programmable_button_report &= ~REPORT_BIT(index);
 }
 
+void programmable_button_register(uint8_t index) {
+    programmable_button_add(index);
+    programmable_button_flush();
+}
+
+void programmable_button_unregister(uint8_t index) {
+    programmable_button_remove(index);
+    programmable_button_flush();
+}
+
 bool programmable_button_is_on(uint8_t index) {
     return !!(programmable_button_report & REPORT_BIT(index));
-};
+}
+
+void programmable_button_flush(void) {
+    host_programmable_button_send(programmable_button_report);
+}
 
 uint32_t programmable_button_get_report(void) {
     return programmable_button_report;
-};
+}
 
 void programmable_button_set_report(uint32_t report) {
     programmable_button_report = report;
diff --git a/quantum/programmable_button.h b/quantum/programmable_button.h
index e89b8b9fd6..e8c916d75c 100644
--- a/quantum/programmable_button.h
+++ b/quantum/programmable_button.h
@@ -19,12 +19,73 @@ along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
 #include <stdint.h>
 #include <stdbool.h>
-#include "report.h"
 
-void     programmable_button_clear(void);
-void     programmable_button_send(void);
-void     programmable_button_on(uint8_t index);
-void     programmable_button_off(uint8_t index);
-bool     programmable_button_is_on(uint8_t index);
+/**
+ * \defgroup programmable_button
+ *
+ * HID Programmable Buttons
+ * \{
+ */
+
+/**
+ * \brief Clear the programmable button report.
+ */
+void programmable_button_clear(void);
+
+/**
+ * \brief Set the state of a button.
+ *
+ * \param index The index of the button to press, from 0 to 31.
+ */
+void programmable_button_add(uint8_t index);
+
+/**
+ * \brief Reset the state of a button.
+ *
+ * \param index The index of the button to release, from 0 to 31.
+ */
+void programmable_button_remove(uint8_t index);
+
+/**
+ * \brief Set the state of a button, and flush the report.
+ *
+ * \param index The index of the button to press, from 0 to 31.
+ */
+void programmable_button_register(uint8_t index);
+
+/**
+ * \brief Reset the state of a button, and flush the report.
+ *
+ * \param index The index of the button to release, from 0 to 31.
+ */
+void programmable_button_unregister(uint8_t index);
+
+/**
+ * \brief Get the state of a button.
+ *
+ * \param index The index of the button to check, from 0 to 31.
+ *
+ * \return `true` if the button is pressed.
+ */
+bool programmable_button_is_on(uint8_t index);
+
+/**
+ * \brief Send the programmable button report to the host.
+ */
+void programmable_button_flush(void);
+
+/**
+ * \brief Get the programmable button report.
+ *
+ * \return The bitmask of programmable button states.
+ */
 uint32_t programmable_button_get_report(void);
-void     programmable_button_set_report(uint32_t report);
+
+/**
+ * \brief Set the programmable button report.
+ *
+ * \param report A bitmask of programmable button states.
+ */
+void programmable_button_set_report(uint32_t report);
+
+/** \} */