Add Doxygen documentation

button.c

@@ -1,13 +1,16 @@
-/*
-* RP2040-Button
-* Button debounce library for Raspberry Pi Pico
-*
-* Fork of https://github.com/jkroso/pico-button.c
-* including https://github.com/jkroso/pico-gpio-interrupt.c,
-* both by Jake Rosoman. MIT license.
-*
-* 2023-02-13: Adapted by Turi Scandurra
-*/
+/**
+ * @file button.c
+ * @brief Button debounce library for Raspberry Pi Pico
+ *
+ * This library provides a simple way to debounce push buttons on a Raspberry Pi Pico.
+ * It generates interrupts after listening to GPIO_IRQ events and allows defining multiple buttons simultaneously.
+ * Fork of https://github.com/jkroso/pico-button.c
+ * including https://github.com/jkroso/pico-gpio-interrupt.c,
+ * both by Jake Rosoman. MIT license.
+ *
+ * @author Turi Scandurra
+ * @date 2023-02-13
+ */
 
 #include <stdio.h>
 #include <stdint.h>
@@ -16,9 +19,24 @@
 
 #include "button.h"
 
+/**
+ * @var handlers
+ * @brief An array of closure structures for GPIO interrupt handlers
+ */
 closure_t handlers[28] = {NULL};
+
+/**
+ * @var alarm_ids
+ * @brief An array of alarm IDs for button debouncing
+ */
 alarm_id_t alarm_ids[28];
 
+/**
+ * @brief Handles a button alarm
+ * @param a The alarm ID (not used)
+ * @param p The button structure
+ * @return 0
+ */
 long long int handle_button_alarm(long int a, void *p) {
   button_t *b = (button_t *)(p);
   bool state = gpio_get(b->pin);
@@ -29,17 +47,33 @@ long long int handle_button_alarm(long int a, void *p) {
   return 0;
 }
 
+/**
+ * @brief Handles a button interrupt
+ * @param p The button structure
+ */
 void handle_button_interrupt(void *p) {
   button_t *b = (button_t *)(p);
   if (alarm_ids[b->pin]) cancel_alarm(alarm_ids[b->pin]);
   alarm_ids[b->pin] = add_alarm_in_us(DEBOUNCE_US, handle_button_alarm, b, true);
 }
 
+/**
+ * @brief Handles a GPIO interrupt
+ * @param gpio The GPIO pin number
+ * @param events The interrupt events
+ */
 void handle_interrupt(uint gpio, uint32_t events) {
   closure_t handler = handlers[gpio];
   handler.fn(handler.argument);
 }
 
+/**
+ * @brief Listens for a GPIO interrupt
+ * @param pin The GPIO pin number
+ * @param condition The interrupt condition
+ * @param fn The callback function
+ * @param arg The argument to be passed to the callback function
+ */
 void listen(uint pin, int condition, handler fn, void *arg) {
   gpio_set_irq_enabled_with_callback(pin, condition, true, handle_interrupt);
   closure_t *handler = malloc(sizeof(closure_t));
@@ -48,6 +82,12 @@ void listen(uint pin, int condition, handler fn, void *arg) {
   handlers[pin] = *handler;
 }
 
+/**
+ * @brief Creates a new button structure
+ * @param pin The GPIO pin number
+ * @param onchange The onchange callback function
+ * @return The new button structure
+ */
 button_t * create_button(int pin, void (*onchange)(button_t *)) {
   gpio_init(pin);
   gpio_pull_up(pin);

button.h

@@ -1,13 +1,16 @@
-/*
-* RP2040-Button
-* Button debounce library for Raspberry Pi Pico
-*
-* Fork of https://github.com/jkroso/pico-button.c
-* including https://github.com/jkroso/pico-gpio-interrupt.c,
-* both by Jake Rosoman. MIT license.
-*
-* 2023-02-13: Adapted by Turi Scandurra
-*/
+/**
+ * @file button.h
+ * @brief Button debounce library for Raspberry Pi Pico
+ *
+ * This library provides a simple way to debounce push buttons on a Raspberry Pi Pico.
+ * It generates interrupts after listening to GPIO_IRQ events and allows defining multiple buttons simultaneously.
+ * Fork of https://github.com/jkroso/pico-button.c
+ * including https://github.com/jkroso/pico-gpio-interrupt.c,
+ * both by Jake Rosoman. MIT license.
+ *
+ * @author Turi Scandurra
+ * @date 2023-02-13
+ */
 
 #ifndef PICO_BUTTON_H
 #define PICO_BUTTON_H
@@ -18,33 +21,97 @@
 extern "C" {
 #endif
 
+/**
+ * @def DEBOUNCE_US
+ * @brief Debounce time in microseconds
+ */
 #define DEBOUNCE_US 200
 
+/**
+ * @struct button_t
+ * @brief Represents a button with its pin, state, and onchange callback
+ */
 typedef struct button_t {
+  /**
+   * @var pin
+   * @brief The GPIO pin number of the button
+   */
   uint8_t pin;
+  /**
+   * @var state
+   * @brief The current state of the button (true for high, false for low)
+   */
   bool state;
+  /**
+   * @var onchange
+   * @brief The callback function to be called when the button state changes
+   */
   void (*onchange)(struct button_t *button);
 } button_t;
 
+/**
+ * @typedef handler
+ * @brief A function pointer type for onchange callbacks
+ */
 typedef void (*handler)(void *argument);
 
+/**
+ * @struct closure_t
+ * @brief Represents a closure with a function pointer and an argument
+ */
 typedef struct {
+  /**
+   * @var argument
+   * @brief The argument to be passed to the function
+   */
   void * argument;
+  /**
+   * @var fn
+   * @brief The function pointer
+   */
   handler fn;
 } closure_t;
 
+/**
+ * @brief Handles a button alarm
+ * @param a The alarm ID (not used)
+ * @param p The button structure
+ * @return 0
+ */
 long long int handle_button_alarm(long int a, void *p);
 
+/**
+ * @brief Handles a button interrupt
+ * @param p The button structure
+ */
 void handle_button_interrupt(void *p);
 
+/**
+ * @brief Handles a GPIO interrupt
+ * @param gpio The GPIO pin number
+ * @param events The interrupt events
+ */
 void handle_interrupt(uint gpio, uint32_t events);
 
+/**
+ * @brief Listens for a GPIO interrupt
+ * @param pin The GPIO pin number
+ * @param condition The interrupt condition
+ * @param fn The callback function
+ * @param arg The argument to be passed to the callback function
+ */
 void listen(uint pin, int condition, handler fn, void *arg);
 
+/**
+ * @brief Creates a new button structure
+ * @param pin The GPIO pin number
+ * @param onchange The onchange callback function
+ * @return The new button structure
+ */
 button_t * create_button(int pin, void (*onchange)(button_t *));
 
 #ifdef __cplusplus
 }
 #endif
 
-#endif
+#endif

example/example.c

@@ -1,9 +1,28 @@
+/**
+ * @file example/example.c
+ * @brief Example usage of the button debounce library
+ */
+
 #include "pico/stdlib.h"
 #include <stdio.h>
-#include <button.h>
-#define PLAY_BUTTON 16  // Button on GPIO 16
-#define PAUSE_BUTTON 17  // Button on GPIO 17
+#include "button.h"
+
+/**
+ * @def PLAY_BUTTON
+ * @brief The GPIO pin number of the play button
+ */
+#define PLAY_BUTTON 16
+
+/**
+ * @def PAUSE_BUTTON
+ * @brief The GPIO pin number of the pause button
+ */
+#define PAUSE_BUTTON 17
 
+/**
+ * @brief Callback function for button state changes
+ * @param button_p The button structure
+ */
 void onchange(button_t *button_p) {
   button_t *button = (button_t*)button_p;
   printf("Button on pin %d changed its state to %d\n", button->pin, button->state);
@@ -21,6 +40,10 @@ void onchange(button_t *button_p) {
   }
 }
 
+/**
+ * @brief Main function
+ * @return 0
+ */
 int main() {
   stdio_init_all();
   button_t *play_button = create_button(PLAY_BUTTON, onchange);