Reformatting doxygen comment markup (RPI docs team)

[nelliemckesson]

This PR reformats the doxygen comment markup to make the generated documentation compatible with doxygen versions > 1.8.17, per discussion with @aallan and @mudge . Here's a summary of the changes:

• Implicit brief descriptions are made explicit, using the \brief tag
• Implicit detailed descriptions are separated from brief descriptions by a blank line
• Inline table markup is updated to use ///< delimiters

Going forward, here are some notes to help maintain compatibility with higher doxygen versions:

Brief Descriptions

Brief descriptions must always be preceded by \brief. Here are several examples:

/**
 * \brief I2C slave event types.
 * \ingroup pico_i2c_slave
 */
typedef enum i2c_slave_event_t
...

/**
 * \file pheap.h
 * \defgroup util_pheap pheap
 * \brief Pairing Heap Implementation
 * \ingroup pico_util
 *
 * pheap defines a simple pairing heap. The implementation simply tracks array indexes, it is up to
 * the user to provide storage for heap entries and a comparison function.
 *
 * NOTE: This class is not safe for concurrent usage. It should be externally protected. Furthermore
 * if used concurrently, the caller needs to protect around their use of the returned id.
 * For example, ph_remove_and_free_head returns the id of an element that is no longer in the heap.
 * The user can still use this to look at the data in their companion array, however obviously further operations
 * on the heap may cause them to overwrite that data as the id may be reused on subsequent operations
 *
 */
// PICO_CONFIG: PICO_PHEAP_MAX_ENTRIES, Maximum number of entries in the pheap, min=1, max=65534, default=255, group=pico_util
#ifndef PICO_PHEAP_MAX_ENTRIES
...

/** \file multicore.h
 *  \defgroup pico_multicore pico_multicore
 * \brief Adds support for running code on the second processor core (core 1)
 *
 * \subsection multicore_example Example
 * \addtogroup pico_multicore
 * \include multicore.c
*/

// PICO_CONFIG: PICO_CORE1_STACK_SIZE, Stack size for core 1, min=0x100, max=0x10000, default=PICO_STACK_SIZE (0x800), group=pico_multicore
#ifndef PICO_CORE1_STACK_SIZE
...

Detailed Descriptions

To add a detailed description, add a blank line after the brief description, or use the \details tag.

Here is an example of an implicit detailed description, where the description text is preceded by a blank line:

/** \file pico/divider.h
* \brief High level APIs including combined quotient and remainder functions for 32 and 64 bit accelerated by the hardware divider
* \ingroup pico_divider
*
* These functions all call __aeabi_idiv0 or __aebi_ldiv0 on division by zero
* passing the largest applicably signed value
*
* Functions with unsafe in their name do not save/restore divider state, so are unsafe to call from interrupts. Unsafe functions are slightly faster.
*/

And here is the same text with an explicit detailed description:

/** \file pico/divider.h
* \brief High level APIs including combined quotient and remainder functions for 32 and 64 bit accelerated by the hardware divider
* \ingroup pico_divider
* \details These functions all call __aeabi_idiv0 or __aebi_ldiv0 on division by zero
* passing the largest applicably signed value
*
* Functions with unsafe in their name do not save/restore divider state, so are unsafe to call from interrupts. Unsafe functions are slightly faster.
*/

Inline enum documentation

You can generate a table for enum types using inline comments like this (note the ///< opening delimeter and lack of a closing delimeter):

/**
 * \brief I2C slave event types.
 * \ingroup pico_i2c_slave
 */
typedef enum i2c_slave_event_t
{
    I2C_SLAVE_RECEIVE, ///< Data from master is available for reading. Slave must read from Rx FIFO.
    I2C_SLAVE_REQUEST, ///< Master is requesting data. Slave must write into Tx FIFO.
    I2C_SLAVE_FINISH, ///< Master has sent a Stop or Restart signal. Slave may prepare for the next transfer.
} i2c_slave_event_t;

[aallan]

@kilograham Can you take a quick look over?

These changes are generated from a script. So if you want to rebase to another branch — or if you want to flip this into the internal repo rather than merging here — that's not too much extra work.

Also, thinking things through, it might also be possible to add something into the SDK as a test to catch poorly formatted Doxygen if that's something you'd be in favour of?

[kilograham]

yes, we could add a github action to test for badly formatted Doxygen