Lots of small doxygen fixes

docs/index.h

@@ -48,9 +48,9 @@
  * \cond hardware_watchdog \defgroup hardware_watchdog hardware_watchdog \endcond
  * \cond hardware_xip_cache \defgroup hardware_xip_cache hardware_xip_cache \endcond
  * \cond hardware_xosc \defgroup hardware_xosc hardware_xosc \endcond
- * \cond hardware_powman hardware_powman
- * \cond hardware_hazard3 hardware_hazard3
- * \cond hardware_riscv hardware_riscv
+ * \cond hardware_powman \defgroup hardware_powman hardware_powman \endcond
+ * \cond hardware_hazard3 \defgroup hardware_hazard3 hardware_hazard3 \endcond
+ * \cond hardware_riscv \defgroup hardware_riscv hardware_riscv \endcond
 
  * @}
  *

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

@@ -23,18 +23,18 @@ typedef unsigned int uint;
 #endif
 
 /*! \typedef absolute_time_t
-    \brief An opaque 64 bit timestamp in microseconds
-
-    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.
-
-    note: As of SDK 2.0.0 this type defaults to being a uin64_t (i.e. no protection); it is enabled
-    by setting PICO_OPAQUE_ABSOLUTE_TIME_T to 1
-
-    \see to_us_since_boot()
-    \see update_us_since_boot()
-    \ingroup timestamp
-*/
+ *  \brief An opaque 64 bit timestamp in microseconds
+ *
+ * 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.
+ *
+ * note: As of SDK 2.0.0 this type defaults to being a uin64_t (i.e. no protection); it is enabled
+ * by setting PICO_OPAQUE_ABSOLUTE_TIME_T to 1
+ *
+ * \see to_us_since_boot()
+ * \see update_us_since_boot()
+ * \ingroup timestamp
+ */
 #if PICO_OPAQUE_ABSOLUTE_TIME_T
 typedef struct {
     uint64_t _private_us_since_boot;

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

@@ -216,7 +216,7 @@ static inline bool is_nil_time(absolute_time_t t) {
  * \note  These functions should not be called from an IRQ handler.
  *
  * \note  Lower powered sleep requires use of the \link alarm_pool_get_default default alarm pool\endlink which may
- * be disabled by the PICO_TIME_DEFAULT_ALARM_POOL_DISABLED #define or currently full in which case these functions
+ * be disabled by the PICO_TIME_DEFAULT_ALARM_POOL_DISABLED \#define or currently full in which case these functions
  * become busy waits instead.
  *
  * \note  Whilst \a sleep_ functions are preferable to \a busy_wait functions from a power perspective, the \a busy_wait equivalent function
@@ -420,7 +420,7 @@ alarm_pool_timer_t *alarm_pool_get_default_timer(void);
  * \param max_timers the maximum number of timers
  *        \note For implementation reasons this is limited to PICO_PHEAP_MAX_ENTRIES which defaults to 255
  * \sa alarm_pool_get_default()
- * \sa hardware_claiming
+ * \sa hardware_claim
  */
 static inline alarm_pool_t *alarm_pool_create(uint timer_alarm_num, uint max_timers) {
     return alarm_pool_create_on_timer(alarm_pool_get_default_timer(), timer_alarm_num, max_timers);
@@ -443,7 +443,7 @@ alarm_pool_t *alarm_pool_create_on_timer_with_unused_hardware_alarm(alarm_pool_t
  * \param max_timers the maximum number of timers
  *        \note For implementation reasons this is limited to PICO_PHEAP_MAX_ENTRIES which defaults to 255
  * \sa alarm_pool_get_default()
- * \sa hardware_claiming
+ * \sa hardware_claim
  */
 static inline alarm_pool_t *alarm_pool_create_with_unused_hardware_alarm(uint max_timers) {
     return alarm_pool_create_on_timer_with_unused_hardware_alarm(alarm_pool_get_default_timer(), max_timers);

src/rp2_common/hardware_dma/include/hardware/dma.h

@@ -123,7 +123,7 @@ int dma_claim_unused_channel(bool required);
  * \param channel the dma channel
  * \return true if the channel is claimed, false otherwise
  * \see dma_channel_claim
- * \see dma_channel_claim_mask
+ * \see dma_claim_mask
  */
 bool dma_channel_is_claimed(uint channel);
 

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

@@ -204,6 +204,11 @@ enum gpio_irq_level {
  */
 typedef void (*gpio_irq_callback_t)(uint gpio, uint32_t event_mask);
 
+/*! \brief GPIO override modes
+ *  \ingroup hardware_gpio
+ *
+ * \sa gpio_set_irqover, gpio_set_outover, gpio_set_inover, gpio_set_oeover
+ */
 enum gpio_override {
     GPIO_OVERRIDE_NORMAL = 0,      ///< peripheral signal selected via \ref gpio_set_function
     GPIO_OVERRIDE_INVERT = 1,      ///< invert peripheral signal selected via \ref gpio_set_function

src/rp2_common/hardware_i2c/include/hardware/i2c.h

@@ -325,9 +325,9 @@ int i2c_write_blocking(i2c_inst_t *i2c, uint8_t addr, const uint8_t *src, size_t
  *
  * \param i2c Either \ref i2c0 or \ref i2c1
  * \param addr 7-bit address of device to read from
- * \param dst Pointer to buffer to receive data
+ * \param src Pointer to data to send
  * \param len Length of data in bytes to receive
- * \return Number of bytes read, or PICO_ERROR_GENERIC if address not acknowledged or no device present.
+ * \return Number of bytes written, or PICO_ERROR_GENERIC if address not acknowledged or no device present.
  */
 int i2c_write_burst_blocking(i2c_inst_t *i2c, uint8_t addr, const uint8_t *src, size_t len);
 

src/rp2_common/hardware_interp/include/hardware/interp.h

@@ -107,7 +107,7 @@ void interp_unclaim_lane(interp_hw_t *interp, uint lane);
  */
 bool interp_lane_is_claimed(interp_hw_t *interp, uint lane);
 
-/*! \brief Release previously claimed interpolator lanes \see interp_claim_lane_mask
+/*! \brief Release previously claimed interpolator lanes, see \ref interp_claim_lane_mask
  *  \ingroup hardware_interp
  *
  * \param interp Interpolator on which to release lanes. interp0 or interp1

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

@@ -680,7 +680,7 @@ static inline void sm_config_set_out_shift(pio_sm_config *c, bool shift_right, b
  *  \ingroup sm_config
  *
  * \param c Pointer to the configuration structure to modify
- * \param join Specifies the join type. \see enum pio_fifo_join
+ * \param join Specifies the join type. See \ref pio_fifo_join
  */
 static inline void sm_config_set_fifo_join(pio_sm_config *c, enum pio_fifo_join join) {
     valid_params_if(HARDWARE_PIO, join == PIO_FIFO_JOIN_NONE || join == PIO_FIFO_JOIN_TX || join == PIO_FIFO_JOIN_RX
@@ -720,7 +720,7 @@ static inline void sm_config_set_out_special(pio_sm_config *c, bool sticky, bool
  *  \ingroup sm_config
  *
  * \param c Pointer to the configuration structure to modify
- * \param status_sel the status operation selector. \see enum pio_mov_status_type
+ * \param status_sel the status operation selector. See \ref pio_mov_status_type
  * \param status_n parameter for the mov status operation (currently a bit count)
  */
 static inline void sm_config_set_mov_status(pio_sm_config *c, enum pio_mov_status_type status_sel, uint status_n) {
@@ -849,7 +849,7 @@ static inline uint pio_get_index(PIO pio) {
  *
  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
  * \return the PIO instance number (0, 1, ...)
- * \see gpio_function
+ * \see gpio_function_t
  */
 static inline uint pio_get_funcsel(PIO pio) {
     check_pio_param(pio);
@@ -948,7 +948,7 @@ bool pio_can_add_program_at_offset(PIO pio, const pio_program_t *program, uint o
 /*! \brief Attempt to load the program
  *  \ingroup hardware_pio
  *
- * \see pio_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; e.g. \ref pio0 or \ref pio1
  * \param program the program definition
@@ -960,7 +960,7 @@ int pio_add_program(PIO pio, const pio_program_t *program);
 /*! \brief Attempt to load the program at the specified instruction memory offset
  *  \ingroup hardware_pio
  *
- * \see pio_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; e.g. \ref pio0 or \ref pio1
  * \param program the program definition
@@ -998,15 +998,15 @@ void pio_clear_instruction_memory(PIO pio);
  *
  * The state machine is left disabled on return from this call.
  *
-* * \if rp2350_specific
+ * \if rp2350_specific
  * See \ref sm_config_pins "sm_config_ pins" for more detail on why this method might fail on RP2350B
  * \endif
  * 
  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
  * \param sm State machine index (0..3)
  * \param initial_pc the initial program memory offset to run from
  * \param config the configuration to apply (or NULL to apply defaults)
- * \return PICO_OK, or < 0 for an error (see \enum pico_error_codes)
+ * \return PICO_OK, or < 0 for an error (see \ref pico_error_codes)
  */
 int pio_sm_init(PIO pio, uint sm, uint initial_pc, const pio_sm_config *config);
 
@@ -1029,7 +1029,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; e.g. \ref pio0 or \ref pio1
@@ -1049,7 +1049,7 @@ static inline void pio_set_sm_mask_enabled(PIO pio, uint32_t mask, 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; e.g. \ref pio0 or \ref pio1
@@ -1419,7 +1419,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; e.g. \ref pio0 or \ref pio1
@@ -1450,7 +1450,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; e.g. \ref pio0 or \ref pio1
@@ -1982,7 +1982,7 @@ bool pio_sm_is_claimed(PIO pio, uint sm);
  * \param sm Returns the index of the PIO state machine that was claimed
  * \param offset Returns the instruction memory offset of the start of the program
  * \return true on success, false otherwise
- * \see pio_remove_program_unclaim_sm
+ * \see pio_remove_program_and_unclaim_sm
  */
 bool pio_claim_free_sm_and_add_program(const pio_program_t *program, PIO *pio, uint *sm, uint *offset);
 
@@ -1994,7 +1994,7 @@ bool pio_claim_free_sm_and_add_program(const pio_program_t *program, PIO *pio, u
  * PIO instance can interact with both pins 0->15 or 32->47 at the same time.
  *
  * This method takes additional information about the GPIO pins needed (via gpio_base and gpio_count),
- * and optionally will set the GPIO base (\see pio_set_gpio_base) of an unused PIO instance if necessary
+ * and optionally will set the GPIO base (see \ref pio_set_gpio_base) of an unused PIO instance if necessary
  *
  * \param program PIO program to add
  * \param pio Returns the PIO hardware instance or NULL if no PIO is available
@@ -2006,7 +2006,7 @@ bool pio_claim_free_sm_and_add_program(const pio_program_t *program, PIO *pio, u
  *                      instance, then that PIO will be reconfigured so that this method can succeed
  *
  * \return true on success, false otherwise
- * \see pio_remove_program_unclaim_sm
+ * \see pio_remove_program_and_unclaim_sm
  */
 bool pio_claim_free_sm_and_add_program_for_gpio_range(const pio_program_t *program, PIO *pio, uint *sm, uint *offset, uint gpio_base, uint gpio_count, bool set_gpio_base);
 

src/rp2_common/hardware_resets/include/hardware/resets.h

@@ -23,6 +23,8 @@
  *
  * Multiple blocks are referred to using a bitmask as follows:
  *
+ * \if rp2040_specific
+ * For RP2040:
  * Block to reset | Bit
  * ---------------|----
  * USB | 24
@@ -41,15 +43,51 @@
  * PIO 1 | 11
  * PIO 0 | 10
  * Pads - QSPI | 9
- * Pads - bank 0 | 8
+ * Pads - Bank 0 | 8
  * JTAG | 7
- * IO Bank 1 | 6
+ * IO QSPI | 6
  * IO Bank 0 | 5
  * I2C 1 | 4
  * I2C 0 | 3
  * DMA | 2
  * Bus Control | 1
  * ADC 0 | 0
+ * \endif
+ *
+ * \if rp2350_specific
+ * For RP2350:
+ * Block to reset | Bit
+ * ---------------|----
+ * USB | 28
+ * UART 1 | 27
+ * UART 0 | 26
+ * TRNG | 25
+ * Timer 1 | 24
+ * Timer 0 | 23
+ * TB Manager | 22
+ * SysInfo | 21
+ * System Config | 20
+ * SPI 1 | 19
+ * SPI 0 | 18
+ * SHA256 | 17
+ * PWM | 16
+ * PLL USB | 15
+ * PLL System | 14
+ * PIO 2 | 13
+ * PIO 1 | 12
+ * PIO 0 | 11
+ * Pads - QSPI | 10
+ * Pads - Bank 0 | 9
+ * JTAG | 8
+ * IO QSPI | 7
+ * IO Bank 0 | 6
+ * I2C 1 | 5
+ * I2C 0 | 4
+ * HSTX | 3
+ * DMA | 2
+ * Bus Control | 1
+ * ADC 0 | 0
+ * \endif
  *
  * \subsection reset_example Example
  * \addtogroup hardware_resets

src/rp2_common/hardware_sha256/include/hardware/sha256.h

@@ -122,7 +122,7 @@ static inline bool sha256_is_sum_valid(void) {
  *  \ingroup hardware_sha256
  *
  * After writing 64 bytes of data to the hardware, it will be unable to accept more data for a time.
- * Call this to check if the hardware is ready for more data to be written. \see sha256_err_not_ready
+ * Call this to check if the hardware is ready for more data to be written. See \ref sha256_err_not_ready
  *
  * \return True if the hardware is ready to receive more data
  */

src/rp2_common/hardware_spi/include/hardware/spi.h

@@ -202,7 +202,7 @@ uint spi_set_baudrate(spi_inst_t *spi, uint baudrate);
 /*! \brief Get SPI baudrate
  *  \ingroup hardware_spi
  *
- * Get SPI baudrate which was set by \see spi_set_baudrate
+ * Get SPI baudrate which was set by \ref spi_set_baudrate
  *
  * \param spi SPI instance specifier, either \ref spi0 or \ref spi1
  * \return The actual baudrate set

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

@@ -351,7 +351,7 @@ typedef void (*hardware_alarm_callback_t)(uint alarm_num);
  * \param timer the timer instance
  * \param alarm_num the hardware alarm to claim
  * \sa hardware_alarm_claim
- * \sa hardware_claiming
+ * \sa hardware_claim
  */
 void timer_hardware_alarm_claim(timer_hw_t *timer, uint alarm_num);
 
@@ -362,7 +362,7 @@ void timer_hardware_alarm_claim(timer_hw_t *timer, uint alarm_num);
  *
  * \param alarm_num the hardware alarm to claim
  * \sa timer_hardware_alarm_claim
- * \sa hardware_claiming
+ * \sa hardware_claim
  */
 void hardware_alarm_claim(uint alarm_num);
 
@@ -375,7 +375,7 @@ void hardware_alarm_claim(uint alarm_num);
  * \param required if true the function will panic if none are available
  * \return alarm_num the hardware alarm claimed or -1 if required was false, and none are available
  * \sa hardware_alarm_claim_unused
- * \sa hardware_claiming
+ * \sa hardware_claim
  */
 int timer_hardware_alarm_claim_unused(timer_hw_t *timer, bool required);
 
@@ -387,7 +387,7 @@ int timer_hardware_alarm_claim_unused(timer_hw_t *timer, bool required);
  * \param required if true the function will panic if none are available
  * \return alarm_num the hardware alarm claimed or -1 if required was false, and none are available
  * \sa timer_hardware_alarm_claim_unused
- * \sa hardware_claiming
+ * \sa hardware_claim
  */
 int hardware_alarm_claim_unused(bool required);
 
@@ -397,7 +397,7 @@ int hardware_alarm_claim_unused(bool required);
  * \param timer the timer instance
  * \param alarm_num the hardware alarm to unclaim
  * \sa hardware_alarm_unclaim
- * \sa hardware_claiming
+ * \sa hardware_claim
  */
 void timer_hardware_alarm_unclaim(timer_hw_t *timer, uint alarm_num);
 
@@ -406,7 +406,7 @@ void timer_hardware_alarm_unclaim(timer_hw_t *timer, uint alarm_num);
  *
  * \param alarm_num the hardware alarm to unclaim
  * \sa timer_hardware_alarm_unclaim
- * \sa hardware_claiming
+ * \sa hardware_claim
  */
 void hardware_alarm_unclaim(uint alarm_num);
 

src/rp2_common/pico_async_context/include/pico/async_context.h

@@ -84,8 +84,8 @@ typedef struct async_context async_context_t;
  *  A "timeout" represents some future action that must be taken at a specific time.
  *  Its methods are called from the async_context under lock at the given time
  *
- * \see async_context_add_worker_at
- * \see async_context_add_worker_in_ms
+ * \see async_context_add_at_time_worker_at
+ * \see async_context_add_at_time_worker_in_ms
  */
 typedef struct async_work_on_timeout {
     /*!
@@ -119,8 +119,8 @@ typedef struct async_work_on_timeout {
  *  to some external stimulus (usually an IRQ).
  *  Its methods are called from the async_context under lock at the given time
  *
- * \see async_context_add_worker_at
- * \see async_context_add_worker_in_ms
+ * \see async_context_add_at_time_worker_at
+ * \see async_context_add_at_time_worker_in_ms
  */
 typedef struct async_when_pending_worker {
     /*!