Small doxygen fixes (#1828)

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

@@ -584,7 +584,7 @@ int64_t alarm_pool_remaining_alarm_time_us(alarm_pool_t *pool, alarm_id_t alarm_
  * @param pool the alarm_pool containing the alarm
  * @param alarm_id the alarm
  *
- * @return >=0 the number of microseconds before the next trigger (INT32_MAX if the number of ms is higher than can be represented0
+ * @return >=0 the number of milliseconds before the next trigger (INT32_MAX if the number of ms is higher than can be represented0
  * @return <0 if either the given alarm is not in progress or it has passed
  */
 int32_t alarm_pool_remaining_alarm_time_ms(alarm_pool_t *pool, alarm_id_t alarm_id);
@@ -700,7 +700,7 @@ int64_t remaining_alarm_time_us(alarm_id_t alarm_id);
  *
  * @param alarm_id the alarm
  *
- * @return >=0 the number of microseconds before the next trigger (INT32_MAX if the number of ms is higher than can be represented0
+ * @return >=0 the number of milliseconds before the next trigger (INT32_MAX if the number of ms is higher than can be represented0
  * @return <0 if either the given alarm is not in progress or it has passed
  */
 int32_t remaining_alarm_time_ms(alarm_id_t alarm_id);

src/common/pico_util/include/pico/util/pheap.h

@@ -54,6 +54,7 @@ typedef struct pheap_node {
 
 /**
  * \brief A user comparator function for nodes in a pairing heap.
+ * \ingroup util_pheap
  *
  * \return true if a < b in natural order. Note this relative ordering must be stable from call to call.
  */
@@ -75,6 +76,7 @@ typedef struct pheap {
  * of nodes. The heap itself stores no user per-node state, it is expected
  * that the user maintains a companion array. A comparator function must
  * be provided so that the heap implementation can determine the relative ordering of nodes
+ * \ingroup util_pheap
  *
  * \param max_nodes the maximum number of nodes that may be in the heap (this is bounded by
  *                  PICO_PHEAP_MAX_ENTRIES which defaults to 255 to be able to store indexes
@@ -87,12 +89,14 @@ pheap_t *ph_create(uint max_nodes, pheap_comparator comparator, void *user_data)
 
 /**
  * \brief Removes all nodes from the pairing heap
+ * \ingroup util_pheap
  * \param heap the heap
  */
 void ph_clear(pheap_t *heap);
 
 /**
  * \brief De-allocates a pairing heap
+ * \ingroup util_pheap
  *
  * Note this method must *ONLY* be called on heaps created by ph_create()
  * \param heap the heap
@@ -136,6 +140,7 @@ static pheap_node_id_t ph_merge_nodes(pheap_t *heap, pheap_node_id_t a, pheap_no
 
 /**
  * \brief Allocate a new node from the unused space in the heap
+ * \ingroup util_pheap
  *
  * \param heap the heap
  * \return an identifier for the node, or 0 if the heap is full
@@ -152,6 +157,7 @@ static inline pheap_node_id_t ph_new_node(pheap_t *heap) {
 
 /**
  * \brief Inserts a node into the heap.
+ * \ingroup util_pheap
  *
  * This method inserts a node (previously allocated by ph_new_node())
  * into the heap, determining the correct order by calling
@@ -172,6 +178,7 @@ static inline pheap_node_id_t ph_insert_node(pheap_t *heap, pheap_node_id_t id)
 /**
  * \brief Returns the head node in the heap, i.e. the node
  * which compares first, but without removing it from the heap.
+ * \ingroup util_pheap
  *
  * \param heap the heap
  * \return the current head node id
@@ -184,6 +191,7 @@ static inline pheap_node_id_t ph_peek_head(pheap_t *heap) {
  * \brief Remove the head node from the pairing heap. This head node is
  * the node which compares first in the logical ordering provided
  * by the comparator.
+ * \ingroup util_pheap
  *
  * Note that in the case of free == true, the returned id is no longer
  * allocated and may be re-used by future node allocations, so the caller
@@ -201,6 +209,7 @@ pheap_node_id_t ph_remove_head(pheap_t *heap, bool free);
  * \brief Remove the head node from the pairing heap. This head node is
  * the node which compares first in the logical ordering provided
  * by the comparator.
+ * \ingroup util_pheap
  *
  * Note that the returned id will be freed, and thus may be re-used by future node allocations,
  * so the caller should retrieve any per node state from the companion array before modifying
@@ -216,6 +225,7 @@ static inline pheap_node_id_t ph_remove_and_free_head(pheap_t *heap) {
 /**
  * \brief Remove and free an arbitrary node from the pairing heap. This is a more
  * costly operation than removing the head via ph_remove_and_free_head()
+ * \ingroup util_pheap
  *
  * @param heap the heap
  * @param id the id of the node to free
@@ -226,6 +236,7 @@ bool ph_remove_and_free_node(pheap_t *heap, pheap_node_id_t id);
 /**
  * \brief Determine if the heap contains a given node. Note containment refers
  * to whether the node is inserted (ph_insert_node()) vs allocated (ph_new_node())
+ * \ingroup util_pheap
  *
  * @param heap the heap
  * @param id the id of the node
@@ -238,6 +249,7 @@ static inline bool ph_contains_node(pheap_t *heap, pheap_node_id_t id) {
 
 /**
  * \brief Free a node that is not currently in the heap, but has been allocated
+ * \ingroup util_pheap
  *
  * @param heap the heap
  * @param id the id of the node
@@ -256,6 +268,7 @@ static inline void ph_free_node(pheap_t *heap, pheap_node_id_t id) {
 
 /**
  * \brief Print a representation of the heap for debugging
+ * \ingroup util_pheap
  *
  * @param heap the heap
  * @param dump_key a method to print a node value
@@ -266,6 +279,7 @@ void ph_dump(pheap_t *heap, void (*dump_key)(pheap_node_id_t id, void *user_data
 /**
  * \brief Initialize a statically allocated heap (ph_create() using the C heap).
  * The heap member `nodes` must be allocated of size max_nodes.
+ * \ingroup util_pheap
  *
  * @param heap the heap
  * @param max_nodes the max number of nodes in the heap (matching the size of the heap's nodes array)
@@ -277,6 +291,7 @@ void ph_post_alloc_init(pheap_t *heap, uint max_nodes, pheap_comparator comparat
 /**
  * \brief Define a statically allocated pairing heap. This must be initialized
  * by ph_post_alloc_init
+ * \ingroup util_pheap
  */
 #define PHEAP_DEFINE_STATIC(name, _max_nodes) \
     static_assert(_max_nodes && _max_nodes < (1u << (8 * sizeof(pheap_node_id_t))), ""); \

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

@@ -911,7 +911,7 @@ static inline uint dma_get_timer_dreq(uint timer_num) {
  *  \ingroup hardware_dma
  *
  * \param irq_index 0 the DMA irq index
- * \return The \ref irq_num_to use for DMA
+ * \return The \ref irq_num_t to use for DMA
  */
 static inline int dma_get_irq_num(uint irq_index) {
     valid_params_if(HARDWARE_DMA, irq_index < NUM_DMA_IRQS);

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

@@ -249,7 +249,7 @@ static inline void check_gpio_param(__unused uint gpio) {
  *  \ingroup hardware_gpio
  *
  * \param gpio GPIO number
- * \param fn Which GPIO function select to use from list \ref gpio_function
+ * \param fn Which GPIO function select to use from list \ref gpio_function_t
  */
 void gpio_set_function(uint gpio, gpio_function_t fn);
 
@@ -258,7 +258,7 @@ void gpio_set_function(uint gpio, gpio_function_t fn);
  *
  * \sa gpio_set_function
  * \param gpio_mask Mask with 1 bit per GPIO number to set the function for
- * \param fn Which GPIO function select to use from list \ref gpio_function
+ * \param fn Which GPIO function select to use from list \ref gpio_function_t
 */
 void gpio_set_function_masked(uint32_t gpio_mask, gpio_function_t fn);
 
@@ -267,15 +267,15 @@ void gpio_set_function_masked(uint32_t gpio_mask, gpio_function_t fn);
  *
  * \sa gpio_set_function
  * \param gpio_mask Mask with 1 bit per GPIO number to set the function for
- * \param fn Which GPIO function select to use from list \ref gpio_function
+ * \param fn Which GPIO function select to use from list \ref gpio_function_t
 */
 void gpio_set_function_masked64(uint64_t gpio_mask, gpio_function_t fn);
 
 /*! \brief Determine current GPIO function
  *  \ingroup hardware_gpio
  *
  * \param gpio GPIO number
- * \return Which GPIO function is currently selected from list \ref gpio_function
+ * \return Which GPIO function is currently selected from list \ref gpio_function_t
  */
 gpio_function_t gpio_get_function(uint gpio);
 

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

@@ -116,7 +116,7 @@ static_assert(TIMER1_IRQ_3 == TIMER0_IRQ_0 + 7, "");
  * \def TIMER_ALARM_NUM_FROM_IRQ(irq_num)
  * \ingroup hardware_timer
  * \hideinitializer
- * \brief Returns the alarm number from an \irq_num_t. See \ref TIMER_INSTANCE_NUM_FROM_IRQ to get the timer instance number
+ * \brief Returns the alarm number from an \ref irq_num_t. See \ref TIMER_INSTANCE_NUM_FROM_IRQ to get the timer instance number
  *
  * Note this macro is intended to resolve at compile time, and does no parameter checking
  */
@@ -134,7 +134,7 @@ static_assert(TIMER1_IRQ_3 == TIMER0_IRQ_0 + 7, "");
  * \def TIMER_NUM_FROM_IRQ(irq_num)
  * \ingroup hardware_timer
  * \hideinitializer
- * \brief Returns the alarm number from an \irq_num_t. See \ref TIMER_INSTANCE_NUM_FROM_IRQ to get the alarm number
+ * \brief Returns the alarm number from an \ref irq_num_t. See \ref TIMER_INSTANCE_NUM_FROM_IRQ to get the alarm number
  *
  * Note this macro is intended to resolve at compile time, and does no parameter checking
  */

src/rp2_common/hardware_uart/include/hardware/uart.h

@@ -213,7 +213,7 @@ static_assert(UART1_IRQ == UART0_IRQ + 1, "");
  *  \ingroup hardware_uart
  *
  * \param uart UART instance
- * \return Number of UART, 0 or 1.
+ * \return Number of UART, 0 or 1
  */
 static inline uint uart_get_index(uart_inst_t *uart) {
     invalid_params_if(HARDWARE_UART, uart != uart0 && uart != uart1);
@@ -223,8 +223,8 @@ static inline uint uart_get_index(uart_inst_t *uart) {
 /*! \brief Get the UART instance from an instance number
  *  \ingroup hardware_uart
  *
- * \param uart UART instance
- * \return Number of UART, 0 or 1
+ * \param num Number of UART, 0 or 1
+ * \return UART instance
  */
 static inline uart_inst_t *uart_get_instance(uint num) {
     invalid_params_if(HARDWARE_UART, num >= NUM_UARTS);
@@ -598,11 +598,10 @@ static inline uint uart_get_dreq_num(uart_inst_t *uart, bool is_tx) {
     return UART_DREQ_NUM(uart, is_tx);
 }
 
-/*! \brief Return the \ref reset_num_t to use for pacing transfers to/from a particular UART instance
+/*! \brief Return the \ref reset_num_t to use to reset a particular UART instance
  *  \ingroup hardware_uart
  *
  * \param uart UART instance. \ref uart0 or \ref uart1
- * \param is_tx true for sending data to the UART instance, false for receiving data from the UART instance
  */
 static inline uint uart_get_reset_num(uart_inst_t *uart) {
     return UART_RESET_NUM(uart);

src/rp2_common/pico_multicore/include/pico/multicore.h

@@ -449,15 +449,15 @@ static inline uint multicore_doorbell_irq_num(uint doorbell_num) {
  */
 void multicore_lockout_victim_init(void);
 
-/*! \brief Determine if \ref multicore_victim_init() has been called on the specified core.
+/*! \brief Determine if \ref multicore_lockout_victim_init() has been called on the specified core.
  *  \ingroup multicore_lockout
  *
  * \note this state persists even if the core is subsequently reset; therefore you are advised to
  * always call \ref multicore_lockout_victim_init() again after resetting a core, which had previously
  * been initialized.
  *
  * \param core_num the core number (0 or 1)
- * \return true if \ref multicore_victim_init() has been called on the specified core, false otherwise.
+ * \return true if \ref multicore_lockout_victim_init() has been called on the specified core, false otherwise.
  */
 bool multicore_lockout_victim_is_initialized(uint core_num);