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

README.md

@@ -85,7 +85,7 @@ instructions for other platforms, and just in general, we recommend you see [Ras
 
           ```
 
-   * Or with automatic download from github :
+   * Or with automatic download from GitHub :
       1. Copy [pico_sdk_import.cmake](https://github.com/raspberrypi/pico-sdk/blob/master/external/pico_sdk_import.cmake)
          from the SDK into your project directory
       1. Setup a `CMakeLists.txt` like:

docs/DoxygenLayout.xml

@@ -12,16 +12,17 @@
       <tab type="user" url="https://rptl.io/pico-c-sdk" visible="yes" title="Raspberry Pi Pico C/C++ SDK" intro=""/>
       <tab type="user" url="https://rptl.io/pico-micropython" visible="yes" title="Raspberry Pi Pico Python SDK" intro=""/>
       <tab type="user" url="https://rptl.io/pico-get-started" visible="yes" title="Getting started with Raspberry Pi Pico" intro=""/>
+      <tab type="user" url="https://rptl.io/pico-faq" visible="yes" title="Raspberry Pi Pico FAQ" intro=""/>
     </tab>
     <tab type="usergroup" url="@ref weblinks_page" visible="yes" title="Web" intro="useful weblinks">
       <tab type="user" url="https://www.raspberrypi.org/" visible="yes" title="Raspberry Pi Site" intro=""/>
       <tab type="user" url="https://rptl.io/rp2040-get-started" visible="yes" title="Raspberry Pi Pico Page" intro=""/>
       <tab type="user" url="https://www.raspberrypi.org/forums" visible="yes" title="Raspberry Pi Forums" intro=""/>
-      <tab type="user" url="https://github.com/raspberrypi/pico-sdk" visible="yes" title="Raspberry Pi Pico SDK on Github" intro=""/>
+      <tab type="user" url="https://github.com/raspberrypi/pico-sdk" visible="yes" title="Raspberry Pi Pico SDK on GitHub" intro=""/>
-      <tab type="user" url="https://github.com/raspberrypi/pico-examples" visible="yes" title="Pico Examples on Github" intro=""/>
+      <tab type="user" url="https://github.com/raspberrypi/pico-examples" visible="yes" title="Pico Examples on GitHub" intro=""/>
-      <tab type="user" url="https://github.com/raspberrypi/pico-extras" visible="yes" title="Pico Extras on Github" intro=""/>
+      <tab type="user" url="https://github.com/raspberrypi/pico-extras" visible="yes" title="Pico Extras on GitHub" intro=""/>
-      <tab type="user" url="https://github.com/raspberrypi/pico-playground" visible="yes" title="Pico Playground on Github" intro=""/>
+      <tab type="user" url="https://github.com/raspberrypi/pico-playground" visible="yes" title="Pico Playground on GitHub" intro=""/>
-      <tab type="user" url="https://github.com/raspberrypi/pico-bootrom" visible="yes" title="Pico Bootrom on Github" intro=""/>
+      <tab type="user" url="https://github.com/raspberrypi/pico-bootrom" visible="yes" title="Pico Bootrom on GitHub" intro=""/>
     </tab>
     <tab type="pages" visible="no" title="" intro=""/>
     <tab type="namespaces" visible="yes" title="">

docs/index.h

@@ -62,8 +62,10 @@
  * @{
  * \defgroup boot_stage2 boot_stage2
  * \defgroup pico_base pico_base
+ * \defgroup pico_binary_info pico_binary_info
  * \defgroup pico_bit_ops pico_bit_ops
  * \defgroup pico_bootrom pico_bootrom
+ * \defgroup pico_bootsel_via_double_reset pico_bootsel_via_double_reset
  * \defgroup pico_cxx_options pico_cxx_options
  * \defgroup pico_divider pico_divider
  * \defgroup pico_double pico_double

docs/weblinks_page.md

@@ -3,11 +3,12 @@
 The full documentation for the RP2040 and Raspberry Pi Pico board can be found at the following links
 
  - [RP2040 Datasheet](https://rptl.io/rp2040-datasheet)
- - [Raspberry Pi Pico datasheet](https://rptl.io/pico-datasheet)
+ - [Raspberry Pi Pico Datasheet](https://rptl.io/pico-datasheet)
- - [Hardware Design with the RP2040](https://rptl.io/rp2040-design)
+ - [Hardware design with the RP2040](https://rptl.io/rp2040-design)
  - [Raspberry Pi Pico C/C++ SDK](https://rptl.io/pico-c-sdk)
  - [Raspberry Pi Pico Python SDK](https://rptl.io/pico-micropython)
- - [Getting Started with Raspberry Pi Pico](https://rptl.io/pico-get-started)
+ - [Getting started with Raspberry Pi Pico](https://rptl.io/pico-get-started)
+ - [Raspberry Pi Pico FAQ](https://rptl.io/pico-faq)
 
 ### Weblinks
 
@@ -19,9 +20,9 @@ For the main Raspberry Pi website, [see here](https://www.raspberrypi.org)
 
 For the Raspberry Pi Pico page, [see here](https://rptl.io/rp2040-get-started)
 
-### Github
+### GitHub
 
-All the source code for the Raspberry Pi Pico SDK, examples and other libraries can be found on Github.
+All the source code for the Raspberry Pi Pico SDK, examples and other libraries can be found on GitHub.
 
  - [Raspberry Pi Pico SDK](https://github.com/raspberrypi/pico-sdk)
  - [Pico Examples](https://github.com/raspberrypi/pico-examples)

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 to_us_since_boot()
-    \see update_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:

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;});
 

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_set_exclusive_handler()
- * \see irq_add_shared_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) {}