pico_status_led doxygen improvements (#2601)

Author: lurch

src/rp2_common/pico_status_led/include/pico/status_led.h

@@ -9,8 +9,9 @@
  *
  * \brief Enables access to the on-board status LED(s)
  *
- * Boards usually have access to an on-board status LEDs which are configured via the board header (\see PICO_DEFAULT_LED_PIN and \see PICO_DEFAULT_WS2812_PIN)
- * This library hides the details so you can use the status LEDs for all boards without changing your code.
+ * Boards usually have access to one or two on-board status LEDs which are configured via the board header (PICO_DEFAULT_LED_PIN, CYW43_WL_GPIO_LED_PIN and/or PICO_DEFAULT_WS2812_PIN).
+ * This library hides the low-level details so you can use the status LEDs for all boards without changing your code.
+ * \note If your board has both a single-color LED and a colored LED, you can independently control the single-color LED with the `status_led_` APIs, and the colored LED with the `colored_status_led_` APIs
  */
 
 #ifndef _PICO_STATUS_LED_H
@@ -28,7 +29,7 @@ struct async_context;
 extern "C" {
 #endif
 
-// PICO_CONFIG: PICO_STATUS_LED_AVAILABLE, Indicate whether a non-colored status LED is available, type=bool, default=1 if PICO_DEFAULT_LED_PIN or CYW43_WL_GPIO_LED_PIN is defined; may be set by the user to 0 to not use either even if they are available, group=pico_status_led
+// PICO_CONFIG: PICO_STATUS_LED_AVAILABLE, Indicate whether a single-color status LED is available, type=bool, default=1 if PICO_DEFAULT_LED_PIN or CYW43_WL_GPIO_LED_PIN is defined; may be set by the user to 0 to not use either even if they are available, group=pico_status_led
 #ifndef PICO_STATUS_LED_AVAILABLE
 #if defined(PICO_DEFAULT_LED_PIN) || defined(CYW43_WL_GPIO_LED_PIN)
 #define PICO_STATUS_LED_AVAILABLE 1
@@ -66,7 +67,7 @@ extern "C" {
 /*! \brief Generate an WRGB color value for \ref colored_status_led_set_on_with_color
  *  \ingroup pico_status_led
  *
- *  \note: If your hardware does not support a white pixel, the white component is ignored
+ *  \note If your hardware does not support a white pixel, the white component is ignored
  */
 #ifndef PICO_COLORED_STATUS_LED_COLOR_FROM_WRGB
 #define PICO_COLORED_STATUS_LED_COLOR_FROM_WRGB(w, r, g, b) (((w) << 24) | ((r) << 16) | ((g) << 8) | (b))
@@ -92,7 +93,7 @@ extern "C" {
  * If the application already has an async context (e.g. created by cyw43_arch_init) you should use \ref
  * status_led_init_with_context instead and pass it the \ref async_context already created by your application
  *
- * \note: You must call this function (or \ref status_led_init_with_context) before using any other pico_status_led functions.
+ * \note You must call this function (or \ref status_led_init_with_context) before using any other pico_status_led functions.
  *
  * \return Returns true if the LED was initialized successfully, otherwise false on failure
  * \sa status_led_init_with_context
@@ -104,7 +105,7 @@ bool status_led_init(void);
  *
  * Initialize the status LED(s) and the resources they need before use.
  *
- * \note: You must call this function (or \ref status_led_init) before using any other pico_status_led functions.
+ * \note You must call this function (or \ref status_led_init) before using any other pico_status_led functions.
  *
  * \param context An \ref async_context used to communicate with the status LED (e.g. on Pico W or Pico 2 W)
  * \return Returns true if the LED was initialized successfully, otherwise false on failure
@@ -122,19 +123,20 @@ static inline bool colored_status_led_supported(void) {
     return PICO_COLORED_STATUS_LED_AVAILABLE;
 }
 
-/*! \brief Determine if the colored status LED is being used for the non-colored `status_led_` APIs
+/*! \brief Determine if the colored status LED is being used for the single-color `status_led_` APIs
  *  \ingroup pico_status_led
- * \return true if the olored status LED is being used for the non-colored `status_led_` API
+ * \return true if the colored status LED is being used for the single-color `status_led_` API
  * \sa PICO_STATUS_LED_VIA_COLORED_STATUS_LED
  */
 static inline bool status_led_via_colored_status_led(void) {
     return PICO_STATUS_LED_VIA_COLORED_STATUS_LED;
 }
 
-/*! \brief Determine if the non-colored `status_led_` APIs are supported (i.e. if there is a regular LED, and its
+/*! \brief Determine if the single-color `status_led_` APIs are supported (i.e. if there is a regular LED, and its
  *         use isn't disabled via \ref PICO_STATUS_LED_AVAILABLE being set to 0, or if the colored status LED is being used for
+ *         the single-color `status_led_` APIs
  *  \ingroup pico_status_led
- * \return true if the non-colored status LED API is available and expected to produce visible results
+ * \return true if the single-color status LED API is available and expected to produce visible results
  * \sa PICO_STATUS_LED_AVAILABLE
  * \sa PICO_STATUS_LED_VIA_COLORED_STATUS_LED
  */
@@ -148,7 +150,7 @@ static inline bool status_led_supported(void) {
 /*! \brief Set the colored status LED on or off
  *  \ingroup pico_status_led
  *
- * \note: If your hardware does not support a colored status LED (\see PICO_DEFAULT_WS2812_PIN), this function does nothing and returns false.
+ * \note If your hardware does not support a colored status LED (PICO_DEFAULT_WS2812_PIN), this function does nothing and returns false.
  *
  * \param led_on true to turn the colored LED on. Pass false to turn the colored LED off
  * \return true if the colored status LED could be set, otherwise false
@@ -158,7 +160,7 @@ bool colored_status_led_set_state(bool led_on);
 /*! \brief Get the state of the colored status LED
  *  \ingroup pico_status_led
  *
- * \note: If your hardware does not support a colored status LED (\see PICO_DEFAULT_WS2812_PIN), this function returns false.
+ * \note If your hardware does not support a colored status LED (PICO_DEFAULT_WS2812_PIN), this function returns false.
  *
  * \return true if the colored status LED is on, or false if the colored status LED is off
  */
@@ -167,17 +169,17 @@ bool colored_status_led_get_state(void);
 /*! \brief Ensure the colored status LED is on, with the specified color
  *  \ingroup pico_status_led
  *
- * \note: If your hardware does not support a colored status LED (\see PICO_DEFAULT_WS2812_PIN), this function does nothing and returns false.
+ * \note If your hardware does not support a colored status LED (PICO_DEFAULT_WS2812_PIN), this function does nothing and returns false.
  *
  * \param color The color to use for the colored status LED when it is on, in 0xWWRRGGBB format
- * \return true if the coloured status LED could be set, otherwise false on failure
+ * \return true if the colored status LED could be set, otherwise false on failure
  */
 bool colored_status_led_set_on_with_color(uint32_t color);
 
 /*! \brief Get the color used for the status LED value when it is on
  *  \ingroup pico_status_led
  *
- * \note: If your hardware does not support a colored status LED (\see PICO_DEFAULT_WS2812_PIN), this function always returns 0x0.
+ * \note If your hardware does not support a colored status LED (PICO_DEFAULT_WS2812_PIN), this function always returns 0x0.
  *
 * \return The color used for the colored status LED when it is on, in 0xWWRRGGBB format
 */
@@ -186,7 +188,7 @@ uint32_t colored_status_led_get_on_color(void);
 /*! \brief Set the status LED on or off
 *  \ingroup pico_status_led
 *
-* \note: If your hardware does not support a status LED (\see PICO_DEFAULT_LED_PIN), this function does nothing and returns false.
+* \note If your hardware does not support a status LED, this function does nothing and returns false.
 *
 * \param led_on true to turn the LED on. Pass false to turn the LED off
 * \return true if the status LED could be set, otherwise false
@@ -213,7 +215,7 @@ static inline bool status_led_set_state(bool led_on) {
 /*! \brief Get the state of the status LED
  *  \ingroup pico_status_led
  *
- * \note: If your hardware does not support a status LED (\see PICO_DEFAULT_LED_PIN), this function always returns false.
+ * \note If your hardware does not support a status LED, this function always returns false.
  *
  * \return true if the status LED is on, or false if the status LED is off
  */