reformatting doxygen comment markup (#1660)

src/common/boot_picoboot/include/boot/picoboot.h

@@ -18,7 +18,7 @@
 /** \file picoboot.h
 *  \defgroup boot_picoboot boot_picoboot
 *
-* Header file for the PICOBOOT USB interface exposed by an RP2040 in BOOTSEL mode.
+* \brief Header file for the PICOBOOT USB interface exposed by an RP2040 in BOOTSEL mode.
 */
 
 #define PICOBOOT_MAGIC 0x431fd10bu

src/common/boot_uf2/include/boot/uf2.h

@@ -13,7 +13,7 @@
 /** \file uf2.h
 *  \defgroup boot_uf2 boot_uf2
 *
-* Header file for the UF2 format supported by an RP2040 in BOOTSEL mode.
+* \brief Header file for the UF2 format supported by an RP2040 in BOOTSEL mode.
 */
 
 #define UF2_MAGIC_START0 0x0A324655u

src/common/pico_base/include/pico.h

@@ -10,7 +10,7 @@
 /** \file pico.h
  *  \defgroup pico_base pico_base
  *
- * Core types and macros for the Raspberry Pi Pico SDK. This header is intended to be included by all source code
+ * \brief Core types and macros for the Raspberry Pi Pico SDK. This header is intended to be included by all source code
  * as it includes configuration headers and overrides in the correct order
  *
  * This header may be included by assembly code

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

@@ -10,7 +10,7 @@
 /** \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.
+ * \brief 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

@@ -29,12 +29,12 @@
 #define __bi_enclosure_check(x) (x)
 #endif
 /**
- * Declare some binary information that will be included if the contain source file/line is compiled into the binary
+ * \brief 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.
+ * \brief 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

src/common/pico_bit_ops/include/pico/bit_ops.h

@@ -16,7 +16,7 @@ extern "C" {
 /** \file bit_ops.h
 *  \defgroup pico_bit_ops pico_bit_ops
 *
-* Optimized bit manipulation functions.
+* \brief Optimized bit manipulation functions.
 * Additionally provides  replacement implementations of the compiler built-ins __builtin_popcount, __builtin_clz
 * and __bulitin_ctz
 */

src/common/pico_divider/include/pico/divider.h

@@ -16,7 +16,7 @@ extern "C" {
 
 /**
  * \defgroup pico_divider pico_divider
- * Optimized 32 and 64 bit division functions accelerated by the RP2040 hardware divider.
+ * \brief Optimized 32 and 64 bit division functions accelerated by the RP2040 hardware divider.
  * Additionally provides integration with the C `/` and `%` operators
  */
 

src/common/pico_stdlib/include/pico/stdlib.h

@@ -20,7 +20,7 @@ extern "C" {
 /** \file stdlib.h
  *  \defgroup pico_stdlib pico_stdlib
  *
- * Aggregation of a core subset of Raspberry Pi Pico SDK libraries used by most executables along with some additional
+ * \brief Aggregation of a core subset of Raspberry Pi Pico SDK libraries used by most executables along with some additional
  * utility methods. Including pico_stdlib gives you everything you need to get a basic program running
  * which prints to stdout or flashes a LED
  *

src/common/pico_sync/include/pico/lock_core.h

@@ -74,6 +74,7 @@ void lock_init(lock_core_t *core, uint lock_num);
 #ifndef lock_owner_id_t
 /*! \brief  type to use to store the 'owner' of a lock.
  *  \ingroup lock_core
+ *
  * By default this is int8_t as it only needs to store the core number or -1, however it may be
  * overridden if a larger type is required (e.g. for an RTOS task id)
  */
@@ -90,6 +91,7 @@ void lock_init(lock_core_t *core, uint lock_num);
 #ifndef lock_get_caller_owner_id
 /*! \brief  return the owner id for the caller
  *  \ingroup lock_core
+ *
  * By default this returns the calling core number, but may be overridden (e.g. to return an RTOS task id)
  */
 #define lock_get_caller_owner_id() ((lock_owner_id_t)get_core_num())

src/common/pico_sync/include/pico/sync.h

@@ -9,7 +9,7 @@
 
 /** \file pico/sync.h
  *  \defgroup pico_sync pico_sync
- * Synchronization primitives and mutual exclusion
+ * \brief Synchronization primitives and mutual exclusion
  */
 
 #include "pico/sem.h"

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

@@ -17,7 +17,7 @@ extern "C" {
 /** \file time.h
  *  \defgroup pico_time pico_time
  *
- * API for accurate timestamps, sleeping, and time based callbacks
+ * \brief API for accurate timestamps, sleeping, and time based callbacks
  *
  * \note The functions defined here provide a much more powerful and user friendly wrapping around the
  * low level hardware timer functionality. For these functions (and any other SDK functionality

src/common/pico_usb_reset_interface/include/pico/usb_reset_interface.h

@@ -10,7 +10,7 @@
 /** \file usb_reset_interface.h
  *  \defgroup pico_usb_reset_interface pico_usb_reset_interface
  *
- * Definition for the reset interface that may be exposed by the pico_stdio_usb library
+ * \brief Definition for the reset interface that may be exposed by the pico_stdio_usb library
  */
 
 // VENDOR sub-class for the reset interface

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

@@ -21,7 +21,7 @@ extern "C" {
 /**
  * \file pheap.h
  * \defgroup util_pheap pheap
- * Pairing Heap Implementation
+ * \brief Pairing Heap Implementation
  * \ingroup pico_util
  *
  * pheap defines a simple pairing heap. The implementation simply tracks array indexes, it is up to
@@ -53,7 +53,7 @@ typedef struct pheap_node {
 } pheap_node_t;
 
 /**
- * A user comparator function for nodes in a pairing heap.
+ * \brief A user comparator function for nodes in a pairing heap.
  *
  * \return true if a < b in natural order. Note this relative ordering must be stable from call to call.
  */
@@ -71,7 +71,7 @@ typedef struct pheap {
 } pheap_t;
 
 /**
- * Create a pairing heap, which effectively maintains an efficient sorted ordering
+ * \brief Create a pairing heap, which effectively maintains an efficient sorted ordering
  * 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
@@ -86,13 +86,13 @@ typedef struct pheap {
 pheap_t *ph_create(uint max_nodes, pheap_comparator comparator, void *user_data);
 
 /**
- * Removes all nodes from the pairing heap
+ * \brief Removes all nodes from the pairing heap
  * \param heap the heap
  */
 void ph_clear(pheap_t *heap);
 
 /**
- * De-allocates a pairing heap
+ * \brief De-allocates a pairing heap
  *
  * Note this method must *ONLY* be called on heaps created by ph_create()
  * \param heap the heap
@@ -135,7 +135,7 @@ static pheap_node_id_t ph_merge_nodes(pheap_t *heap, pheap_node_id_t a, pheap_no
 }
 
 /**
- * Allocate a new node from the unused space in the heap
+ * \brief Allocate a new node from the unused space in the heap
  *
  * \param heap the heap
  * \return an identifier for the node, or 0 if the heap is full
@@ -151,7 +151,7 @@ static inline pheap_node_id_t ph_new_node(pheap_t *heap) {
 }
 
 /**
- * Inserts a node into the heap.
+ * \brief Inserts a node into the heap.
  *
  * This method inserts a node (previously allocated by ph_new_node())
  * into the heap, determining the correct order by calling
@@ -170,7 +170,7 @@ static inline pheap_node_id_t ph_insert_node(pheap_t *heap, pheap_node_id_t id)
 }
 
 /**
- * Returns the head node in the heap, i.e. the node
+ * \brief Returns the head node in the heap, i.e. the node
  * which compares first, but without removing it from the heap.
  *
  * \param heap the heap
@@ -181,7 +181,7 @@ static inline pheap_node_id_t ph_peek_head(pheap_t *heap) {
 }
 
 /**
- * Remove the head node from the pairing heap. This head node is
+ * \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.
  *
@@ -198,7 +198,7 @@ static inline pheap_node_id_t ph_peek_head(pheap_t *heap) {
 pheap_node_id_t ph_remove_head(pheap_t *heap, bool free);
 
 /**
- * Remove the head node from the pairing heap. This head node is
+ * \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.
  *
@@ -214,7 +214,7 @@ static inline pheap_node_id_t ph_remove_and_free_head(pheap_t *heap) {
 }
 
 /**
- * Remove and free an arbitrary node from the pairing heap. This is a more
+ * \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()
  *
  * @param heap the heap
@@ -224,7 +224,7 @@ static inline pheap_node_id_t ph_remove_and_free_head(pheap_t *heap) {
 bool ph_remove_and_free_node(pheap_t *heap, pheap_node_id_t id);
 
 /**
- * Determine if the heap contains a given node. Note containment refers
+ * \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())
  *
  * @param heap the heap
@@ -237,7 +237,7 @@ static inline bool ph_contains_node(pheap_t *heap, pheap_node_id_t id) {
 
 
 /**
- * Free a node that is not currently in the heap, but has been allocated
+ * \brief Free a node that is not currently in the heap, but has been allocated
  *
  * @param heap the heap
  * @param id the id of the node
@@ -255,7 +255,7 @@ static inline void ph_free_node(pheap_t *heap, pheap_node_id_t id) {
 }
 
 /**
- * Print a representation of the heap for debugging
+ * \brief Print a representation of the heap for debugging
  *
  * @param heap the heap
  * @param dump_key a method to print a node value
@@ -264,7 +264,7 @@ static inline void ph_free_node(pheap_t *heap, pheap_node_id_t id) {
 void ph_dump(pheap_t *heap, void (*dump_key)(pheap_node_id_t id, void *user_data), void *user_data);
 
 /**
- * Initialize a statically allocated heap (ph_create() using the C heap).
+ * \brief Initialize a statically allocated heap (ph_create() using the C heap).
  * The heap member `nodes` must be allocated of size max_nodes.
  *
  * @param heap the heap
@@ -275,7 +275,7 @@ void ph_dump(pheap_t *heap, void (*dump_key)(pheap_node_id_t id, void *user_data
 void ph_post_alloc_init(pheap_t *heap, uint max_nodes, pheap_comparator comparator, void *user_data);
 
 /**
- * Define a statically allocated pairing heap. This must be initialized
+ * \brief Define a statically allocated pairing heap. This must be initialized
  * by ph_post_alloc_init
  */
 #define PHEAP_DEFINE_STATIC(name, _max_nodes) \

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

@@ -17,7 +17,7 @@
 
 /** \file queue.h
  * \defgroup queue queue
- * Multi-core and IRQ safe queue implementation.
+ * \brief Multi-core and IRQ safe queue implementation.
  *
  * Note that this queue stores values of a specified size, and pushed values are copied into the queue
  * \ingroup pico_util

src/rp2_common/cmsis/stub/CMSIS/Core/Include/mpu_armv7.h

@@ -78,7 +78,7 @@
    (MPU_RBAR_VALID_Msk))
 
 /**
-* MPU Memory Access Attributes
+* \brief MPU Memory Access Attributes
 * 
 * \param TypeExtField      Type extension field, allows you to configure memory access type, for example strongly ordered, peripheral.
 * \param IsShareable       Region is shareable between multiple bus masters.
@@ -92,7 +92,7 @@
    (((IsBufferable) << MPU_RASR_B_Pos)   & MPU_RASR_B_Msk))
 
 /**
-* MPU Region Attribute and Size Register Value
+* \brief MPU Region Attribute and Size Register Value
 * 
 * \param DisableExec       Instruction access disable bit, 1= disable instruction fetches.
 * \param AccessPermission  Data access permissions, allows you to configure read/write access for User and Privileged mode.
@@ -109,7 +109,7 @@
    (((MPU_RASR_ENABLE_Msk))))
 
 /**
-* MPU Region Attribute and Size Register Value
+* \brief MPU Region Attribute and Size Register Value
 * 
 * \param DisableExec       Instruction access disable bit, 1= disable instruction fetches.
 * \param AccessPermission  Data access permissions, allows you to configure read/write access for User and Privileged mode.
@@ -124,7 +124,7 @@
   ARM_MPU_RASR_EX(DisableExec, AccessPermission, ARM_MPU_ACCESS_(TypeExtField, IsShareable, IsCacheable, IsBufferable), SubRegionDisable, Size)
 
 /**
-* MPU Memory Access Attribute for strongly ordered memory.
+* \brief MPU Memory Access Attribute for strongly ordered memory.
 *  - TEX: 000b
 *  - Shareable
 *  - Non-cacheable
@@ -133,7 +133,7 @@
 #define ARM_MPU_ACCESS_ORDERED ARM_MPU_ACCESS_(0U, 1U, 0U, 0U)
 
 /**
-* MPU Memory Access Attribute for device memory.
+* \brief MPU Memory Access Attribute for device memory.
 *  - TEX: 000b (if shareable) or 010b (if non-shareable)
 *  - Shareable or non-shareable
 *  - Non-cacheable
@@ -144,7 +144,7 @@
 #define ARM_MPU_ACCESS_DEVICE(IsShareable) ((IsShareable) ? ARM_MPU_ACCESS_(0U, 1U, 0U, 1U) : ARM_MPU_ACCESS_(2U, 0U, 0U, 0U))
 
 /**
-* MPU Memory Access Attribute for normal memory.
+* \brief MPU Memory Access Attribute for normal memory.
 *  - TEX: 1BBb (reflecting outer cacheability rules)
 *  - Shareable or non-shareable
 *  - Cacheable or non-cacheable (reflecting inner cacheability rules)
@@ -157,28 +157,28 @@
 #define ARM_MPU_ACCESS_NORMAL(OuterCp, InnerCp, IsShareable) ARM_MPU_ACCESS_((4U | (OuterCp)), IsShareable, ((InnerCp) >> 1U), ((InnerCp) & 1U))
 
 /**
-* MPU Memory Access Attribute non-cacheable policy.
+* \brief MPU Memory Access Attribute non-cacheable policy.
 */
 #define ARM_MPU_CACHEP_NOCACHE 0U
 
 /**
-* MPU Memory Access Attribute write-back, write and read allocate policy.
+* \brief MPU Memory Access Attribute write-back, write and read allocate policy.
 */
 #define ARM_MPU_CACHEP_WB_WRA 1U
 
 /**
-* MPU Memory Access Attribute write-through, no write allocate policy.
+* \brief MPU Memory Access Attribute write-through, no write allocate policy.
 */
 #define ARM_MPU_CACHEP_WT_NWA 2U
 
 /**
-* MPU Memory Access Attribute write-back, no write allocate policy.
+* \brief MPU Memory Access Attribute write-back, no write allocate policy.
 */
 #define ARM_MPU_CACHEP_WB_NWA 3U
 
 
 /**
-* Struct for a single MPU Region
+* \brief Struct for a single MPU Region
 */
 typedef struct {
   uint32_t RBAR; //!< The region base address register value (RBAR)

src/rp2_common/hardware_adc/include/hardware/adc.h

@@ -14,7 +14,7 @@
 /** \file hardware/adc.h
  *  \defgroup hardware_adc hardware_adc
  *
- * Analog to Digital Converter (ADC) API
+ * \brief Analog to Digital Converter (ADC) API
  *
  * The RP2040 has an internal analogue-digital converter (ADC) with the following features:
  * - SAR ADC

src/rp2_common/hardware_base/include/hardware/address_mapped.h

@@ -13,7 +13,7 @@
 /** \file address_mapped.h
  *  \defgroup hardware_base hardware_base
  *
- *  Low-level types and (atomic) accessors for memory-mapped hardware registers
+ *  \brief Low-level types and (atomic) accessors for memory-mapped hardware registers
  *
  *  `hardware_base` defines the low level types and access functions for memory mapped hardware registers. It is included
  *  by default by all other hardware libraries.

src/rp2_common/hardware_claim/include/hardware/claim.h

@@ -13,7 +13,7 @@
 /** \file claim.h
  *  \defgroup hardware_claim hardware_claim
  *
- *  Lightweight hardware resource management
+ *  \brief Lightweight hardware resource management
  *
  * `hardware_claim` provides a simple API for management of hardware resources at runtime.
  *

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

@@ -17,7 +17,7 @@ extern "C" {
 /** \file hardware/clocks.h
  *  \defgroup hardware_clocks hardware_clocks
  *
- * Clock Management API
+ * \brief Clock Management API
  *
  * This API provides a high level interface to the clock functions.
  *