Lots of Doxygen tweaks and fixes (#212)

* Add documentation for gpio_irq_callback_t and rtc_callback_t (fixes #175)
 * Hook up pico_binary_info and pico_bootsel_via_double_reset to the Doxygen index
 * Add link to new Raspberry Pi Pico FAQ
 * Consistently add parentheses for \sa or \see links to function-names
 * Use consistent capitalisation for 'GitHub'
 * Small typos and markup errors

src/common/pico_base/include/pico/types.h

@@ -21,8 +21,8 @@ typedef unsigned int uint;
     The type is used instead of a raw uint64_t to prevent accidentally passing relative times or times in the wrong
     time units where an absolute time is required. It is equivalent to uint64_t in release builds.
 
-    \see to_us_since_boot
-    \see update_us_since_boot
+    \see to_us_since_boot()
+    \see update_us_since_boot()
     \ingroup timestamp
 */
 #ifndef NDEBUG

src/common/pico_binary_info/include/pico/binary_info.h

@@ -7,7 +7,9 @@
 #ifndef _PICO_BINARY_INFO_H
 #define _PICO_BINARY_INFO_H
 
-/**
+/** \file binary_info.h
+ *  \defgroup pico_binary_info pico_binary_info
+ *
  * Binary info is intended for embedding machine readable information with the binary in FLASH.
  *
  * Example uses include:
@@ -26,4 +28,4 @@
 #if !PICO_NO_BINARY_INFO
 #include "pico/binary_info/code.h"
 #endif
-#endif
+#endif

src/common/pico_binary_info/include/pico/binary_info/code.h

@@ -25,12 +25,14 @@
 #endif
 /**
  * Declare some binary information that will be included if the contain source file/line is compiled into the binary
+ * \ingroup pico_binary_info
  */
 #define bi_decl(_decl) __bi_mark_enclosure _decl; __bi_decl(__bi_ptr_lineno_var_name, &__bi_lineno_var_name.core, ".binary_info.keep.", __used);
 /**
  * Declare some binary information that will be included if the function containing the decl is linked into the binary.
  * The SDK uses --gc-sections, so functions that are never called will be removed by the linker, and any associated
  * binary information declared this way will also be stripped
+ * \ingroup pico_binary_info
  */
 #define bi_decl_if_func_used(_decl) ({__bi_mark_enclosure _decl; __bi_decl(__bi_ptr_lineno_var_name, &__bi_lineno_var_name.core, ".binary_info.", ); *(volatile uint8_t *)&__bi_ptr_lineno_var_name;});
 
@@ -136,4 +138,4 @@ static const struct _binary_info_named_group __bi_lineno_var_name = { \
 #define bi_3pins_with_names(p0, name0, p1, name1, p2, name2)  bi_pin_mask_with_names((1u << (p0)) | (1u << (p1)) | (1u << (p2)), name0 "|" name1 "|" name2)
 #define bi_4pins_with_names(p0, name0, p1, name1, p2, name2, p3, name3)  bi_pin_mask_with_names((1u << (p0)) | (1u << (p1)) | (1u << (p2)) | (1u << (p3)), name0 "|" name1 "|" name2 "|" name3)
 
-#endif
+#endif

src/common/pico_time/include/pico/time.h

@@ -77,7 +77,7 @@ static inline uint32_t us_to_ms(uint64_t us) {
  * \brief Convert a timestamp into a number of milliseconds since boot.
  * \param t an absolute_time_t value to convert
  * \return the number of microseconds since boot represented by t
- * \sa to_us_since_boot
+ * \sa to_us_since_boot()
  */
 static inline uint32_t to_ms_since_boot(absolute_time_t t) {
     uint64_t us = to_us_since_boot(t);
@@ -171,7 +171,7 @@ extern const absolute_time_t nil_time;
  * \ingroup timestamp
  *  \param t the timestamp
  *  \return true if the timestamp is nil
- *  \sa nil_time()
+ *  \sa nil_time
  */
 static inline bool is_nil_time(absolute_time_t t) {
     return !to_us_since_boot(t);
@@ -230,7 +230,7 @@ void sleep_ms(uint32_t ms);
 /*! \brief Helper method for blocking on a timeout
  * \ingroup sleep
  *
- * This method will return in response to a an event (as per __wfe) or
+ * This method will return in response to an event (as per __wfe) or
  * when the target time is reached, or at any point before.
  *
  * This method can be used to implement a lower power polling loop waiting on

src/rp2_common/hardware_clocks/include/hardware/clocks.h

@@ -140,7 +140,7 @@ uint32_t frequency_count_khz(uint src);
 /*! \brief Set the "current frequency" of the clock as reported by clock_get_hz without actually changing the clock
  *  \ingroup hardware_clocks
  *
- * \see clock_get_hz
+ * \see clock_get_hz()
  */
 void clock_set_reported_hz(enum clock_index clk_index, uint hz);
 

src/rp2_common/hardware_gpio/include/hardware/gpio.h

@@ -124,6 +124,13 @@ enum gpio_irq_level {
     GPIO_IRQ_EDGE_RISE = 0x8u,
 };
 
+/*! Callback function type for GPIO events
+ *  \ingroup hardware_gpio
+ *
+ * \param gpio Which GPIO caused this interrupt
+ * \param events Which events caused this interrupt. See \ref gpio_set_irq_enabled for details.
+ * \sa gpio_set_irq_enabled_with_callback()
+ */
 typedef void (*gpio_irq_callback_t)(uint gpio, uint32_t events);
 
 enum gpio_override {
@@ -267,7 +274,7 @@ void gpio_set_irq_enabled(uint gpio, uint32_t events, bool enabled);
  * the processor that calls the function.
  *
  * \param gpio GPIO number
- * \param events Which events will cause an interrupt See \ref gpio_set_irq_enabled for details.
+ * \param events Which events will cause an interrupt. See \ref gpio_set_irq_enabled for details.
  * \param enabled Enable or disable flag
  * \param callback user function to call on GPIO irq. Note only one of these can be set per processor.
  *

src/rp2_common/hardware_irq/include/hardware/irq.h

@@ -166,7 +166,7 @@ void irq_set_mask_enabled(uint32_t mask, bool enabled);
  *
  * \param num Interrupt number \ref interrupt_nums
  * \param handler The handler to set. See \ref irq_handler_t
- * \see irq_add_shared_handler
+ * \see irq_add_shared_handler()
  */
 void irq_set_exclusive_handler(uint num, irq_handler_t handler);
 
@@ -177,7 +177,7 @@ void irq_set_exclusive_handler(uint num, irq_handler_t handler);
  * by irq_set_exclusive_handler if there is one.
  *
  * \param num Interrupt number \ref interrupt_nums
- * \see irq_set_exclusive_handler
+ * \see irq_set_exclusive_handler()
  * \return handler The handler if an exclusive handler is set for the IRQ,
  *                 NULL if no handler is set or shared/shareable handlers are installed
  */
@@ -202,7 +202,7 @@ irq_handler_t irq_get_exclusive_handler(uint num);
  * rule of thumb is to use PICO_SHARED_IRQ_HANDLER_DEFAULT_ORDER_PRIORITY if you don't much care, as it is in the middle of
  * the priority range by default.
  *
- * \see irq_set_exclusive_handler
+ * \see irq_set_exclusive_handler()
  */
 void irq_add_shared_handler(uint num, irq_handler_t handler, uint8_t order_priority);
 
@@ -219,8 +219,8 @@ void irq_add_shared_handler(uint num, irq_handler_t handler, uint8_t order_prior
  *
  * \param num Interrupt number \ref interrupt_nums
  * \param handler The handler to removed.
- * \see irq_set_exclusive_handler
- * \see irq_add_shared_handler
+ * \see irq_set_exclusive_handler()
+ * \see irq_add_shared_handler()
  */
 void irq_remove_handler(uint num, irq_handler_t handler);
 

src/rp2_common/hardware_pio/include/hardware/pio.h

@@ -230,7 +230,7 @@ static inline void sm_config_set_clkdiv(pio_sm_config *c, float div) {
  * \param c Pointer to the configuration structure to modify
  * \param div_int Integer part of the divisor
  * \param div_frac Fractional part in 1/256ths
- * \sa sm_config_set_clkdiv
+ * \sa sm_config_set_clkdiv()
  */
 static inline void sm_config_set_clkdiv_int_frac(pio_sm_config *c, uint16_t div_int, uint8_t div_frac) {
     c->clkdiv =
@@ -463,7 +463,7 @@ bool pio_can_add_program_at_offset(PIO pio, const pio_program_t *program, uint o
 /*! \brief Attempt to load the program, panicking if not possible
  *  \ingroup hardware_pio
  *
- * \see pico_can_add_program if you need to check whether the program can be loaded
+ * \see pio_can_add_program() if you need to check whether the program can be loaded
  *
  * \param pio The PIO instance; either \ref pio0 or \ref pio1
  * \param program the program definition
@@ -474,7 +474,7 @@ uint pio_add_program(PIO pio, const pio_program_t *program);
 /*! \brief Attempt to load the program at the specified instruction memory offset, panicking if not possible
  *  \ingroup hardware_pio
  *
- * \see pico_can_add_program_at_offset if you need to check whether the program can be loaded
+ * \see pio_can_add_program_at_offset() if you need to check whether the program can be loaded
  *
  * \param pio The PIO instance; either \ref pio0 or \ref pio1
  * \param program the program definition
@@ -536,7 +536,7 @@ static inline void pio_sm_set_enabled(PIO pio, uint sm, bool enabled) {
  * Note that this method just sets the enabled state of the state machine;
  * if now enabled they continue exactly from where they left off.
  *
- * \see pio_enable_sm_mask_in_sync if you wish to enable multiple state machines
+ * \see pio_enable_sm_mask_in_sync() if you wish to enable multiple state machines
  * and ensure their clock dividers are in sync.
  *
  * \param pio The PIO instance; either \ref pio0 or \ref pio1
@@ -673,7 +673,7 @@ static inline uint8_t pio_sm_get_pc(PIO pio, uint sm) {
  *
  * This instruction is executed instead of the next instruction in the normal control flow on the state machine.
  * Subsequent calls to this method replace the previous executed
- * instruction if it is still running. \see pio_sm_is_exec_stalled to see if an executed instruction
+ * instruction if it is still running. \see pio_sm_is_exec_stalled() to see if an executed instruction
  * is still running (i.e. it is stalled on some condition)
  *
  * \param pio The PIO instance; either \ref pio0 or \ref pio1
@@ -704,7 +704,7 @@ static inline bool pio_sm_is_exec_stalled(PIO pio, uint sm) {
  *
  * This instruction is executed instead of the next instruction in the normal control flow on the state machine.
  * Subsequent calls to this method replace the previous executed
- * instruction if it is still running. \see pio_sm_is_exec_stalled to see if an executed instruction
+ * instruction if it is still running. \see pio_sm_is_exec_stalled() to see if an executed instruction
  * is still running (i.e. it is stalled on some condition)
  *
  * \param pio The PIO instance; either \ref pio0 or \ref pio1
@@ -825,7 +825,7 @@ static inline void pio_sm_set_sideset_pins(PIO pio, uint sm, uint sideset_base)
  * \param sm State machine index (0..3)
  * \param data the 32 bit data value
  *
- * \sa pio_sm_put_blocking
+ * \sa pio_sm_put_blocking()
  */
 static inline void pio_sm_put(PIO pio, uint sm, uint32_t data) {
     check_pio_param(pio);
@@ -846,7 +846,7 @@ static inline void pio_sm_put(PIO pio, uint sm, uint32_t data) {
  * \param pio The PIO instance; either \ref pio0 or \ref pio1
  * \param sm State machine index (0..3)
  *
- * \sa pio_sm_get_blocking
+ * \sa pio_sm_get_blocking()
  */
 static inline uint32_t pio_sm_get(PIO pio, uint sm) {
     check_pio_param(pio);
@@ -974,7 +974,7 @@ static inline uint32_t pio_sm_get_blocking(PIO pio, uint sm) {
  * \param pio The PIO instance; either \ref pio0 or \ref pio1
  * \param sm State machine index (0..3)
  *
- * \sa pio_sm_clear_fifos
+ * \sa pio_sm_clear_fifos()
  */
 void pio_sm_drain_tx_fifo(PIO pio, uint sm);
 

src/rp2_common/hardware_rtc/include/hardware/rtc.h

@@ -32,6 +32,11 @@
 extern "C" {
 #endif
 
+/*! Callback function type for RTC alarms
+ *  \ingroup hardware_rtc
+ *
+ * \sa rtc_set_alarm()
+ */
 typedef void (*rtc_callback_t)(void);
 
 /*! \brief Initialise the RTC system

src/rp2_common/hardware_timer/include/hardware/timer.h

@@ -115,7 +115,7 @@ static inline bool time_reached(absolute_time_t t) {
  *  \ingroup hardware_timer
  *
  * \param alarm_num the hardware alarm number
- * \sa hardware_alarm_set_callback
+ * \sa hardware_alarm_set_callback()
  */
 typedef void (*hardware_alarm_callback_t)(uint alarm_num);
 
@@ -151,7 +151,7 @@ void hardware_alarm_unclaim(uint alarm_num);
  * \param alarm_num the hardware alarm number
  * \param callback the callback to install, or NULL to unset
  *
- * \sa hardware_alarm_set_target
+ * \sa hardware_alarm_set_target()
  */
 void hardware_alarm_set_callback(uint alarm_num, hardware_alarm_callback_t callback);
 

src/rp2_common/hardware_watchdog/include/hardware/watchdog.h

@@ -32,7 +32,7 @@ extern "C" {
 /*! \brief Define actions to perform at watchdog timeout
  *  \ingroup hardware_watchdog
  *
- * \note If \ref watchdog_start_tick value does not give a 1MHz clock to the watchdog system, then the \ref delay_ms
+ * \note If \ref watchdog_start_tick value does not give a 1MHz clock to the watchdog system, then the \p delay_ms
  * parameter will not be in microseconds. See the datasheet for more details.
  *
  * By default the SDK assumes a 12MHz XOSC and sets the \ref watchdog_start_tick appropriately.
@@ -61,7 +61,7 @@ void watchdog_update(void);
  * \brief Enable the watchdog
  * \ingroup hardware_watchdog
  *
- * \note If \ref watchdog_start_tick value does not give a 1MHz clock to the watchdog system, then the \ref delay_ms
+ * \note If \ref watchdog_start_tick value does not give a 1MHz clock to the watchdog system, then the \p delay_ms
  * parameter will not be in microseconds. See the datasheet for more details.
  *
  * By default the SDK assumes a 12MHz XOSC and sets the \ref watchdog_start_tick appropriately.

src/rp2_common/pico_bootsel_via_double_reset/pico_bootsel_via_double_reset.c

@@ -24,7 +24,7 @@
 #define PICO_BOOTSEL_VIA_DOUBLE_RESET_INTERFACE_DISABLE_MASK 0u
 #endif
 
-/** \defgroup pico_bootsel_via_double_reset
+/** \defgroup pico_bootsel_via_double_reset pico_bootsel_via_double_reset
  *
  * When the 'pico_bootsel_via_double_reset' library is linked, a function is
  * injected before main() which will detect when the system has been reset

src/rp2_common/pico_multicore/multicore.c

@@ -91,7 +91,7 @@ int core1_wrapper(int (*entry)(void), void *stack_base) {
 }
 
 void multicore_reset_core1() {
-    // Use atomic aliases just in case core 1 is also manipulating some posm state
+    // Use atomic aliases just in case core 1 is also manipulating some PSM state
     io_rw_32 *power_off = (io_rw_32 *) (PSM_BASE + PSM_FRCE_OFF_OFFSET);
     io_rw_32 *power_off_set = hw_set_alias(power_off);
     io_rw_32 *power_off_clr = hw_clear_alias(power_off);

src/rp2_common/pico_platform/include/pico/platform.h

@@ -119,7 +119,7 @@ static inline uint8_t rp2040_rom_version(void) {
 
 /**
  * Empty function intended to be called by any tight hardware polling loop. using this ubiquitously
- * makes it much easier to find tight loops, but also in the future #ifdef-ed support for lockup
+ * makes it much easier to find tight loops, but also in the future \#ifdef-ed support for lockup
  * debugging might be added
  */
 static inline void tight_loop_contents(void) {}