From 1bdd006c8d1f7b305254fa3a55bcea232bd5471e Mon Sep 17 00:00:00 2001 From: Andrew Scheller Date: Tue, 20 Aug 2024 18:41:49 +0100 Subject: [PATCH] Small doxygen fixes (#1828) --- src/common/pico_time/include/pico/time.h | 4 ++-- src/common/pico_util/include/pico/util/pheap.h | 15 +++++++++++++++ .../hardware_dma/include/hardware/dma.h | 2 +- .../hardware_gpio/include/hardware/gpio.h | 8 ++++---- .../hardware_timer/include/hardware/timer.h | 4 ++-- .../hardware_uart/include/hardware/uart.h | 9 ++++----- .../pico_multicore/include/pico/multicore.h | 4 ++-- 7 files changed, 30 insertions(+), 16 deletions(-) diff --git a/src/common/pico_time/include/pico/time.h b/src/common/pico_time/include/pico/time.h index 699523e9e..4a9aef5ab 100644 --- a/src/common/pico_time/include/pico/time.h +++ b/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); diff --git a/src/common/pico_util/include/pico/util/pheap.h b/src/common/pico_util/include/pico/util/pheap.h index d51804cdf..402d9cb3a 100644 --- a/src/common/pico_util/include/pico/util/pheap.h +++ b/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))), ""); \ diff --git a/src/rp2_common/hardware_dma/include/hardware/dma.h b/src/rp2_common/hardware_dma/include/hardware/dma.h index dd940ffc7..8bb35ec1f 100644 --- a/src/rp2_common/hardware_dma/include/hardware/dma.h +++ b/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); diff --git a/src/rp2_common/hardware_gpio/include/hardware/gpio.h b/src/rp2_common/hardware_gpio/include/hardware/gpio.h index 029619cfe..1271315a0 100644 --- a/src/rp2_common/hardware_gpio/include/hardware/gpio.h +++ b/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,7 +267,7 @@ 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); @@ -275,7 +275,7 @@ void gpio_set_function_masked64(uint64_t gpio_mask, gpio_function_t fn); * \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); diff --git a/src/rp2_common/hardware_timer/include/hardware/timer.h b/src/rp2_common/hardware_timer/include/hardware/timer.h index 4f57c2bd8..0c0b69f2f 100644 --- a/src/rp2_common/hardware_timer/include/hardware/timer.h +++ b/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 */ diff --git a/src/rp2_common/hardware_uart/include/hardware/uart.h b/src/rp2_common/hardware_uart/include/hardware/uart.h index 4febe1799..0cf2c6eae 100644 --- a/src/rp2_common/hardware_uart/include/hardware/uart.h +++ b/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); diff --git a/src/rp2_common/pico_multicore/include/pico/multicore.h b/src/rp2_common/pico_multicore/include/pico/multicore.h index a45f2a6c7..aa7bb5d71 100644 --- a/src/rp2_common/pico_multicore/include/pico/multicore.h +++ b/src/rp2_common/pico_multicore/include/pico/multicore.h @@ -449,7 +449,7 @@ 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 @@ -457,7 +457,7 @@ void multicore_lockout_victim_init(void); * 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);