From 2e7753a6b1b3ab94f345c89115d2d4f74f4afb9f Mon Sep 17 00:00:00 2001 From: Andrew Scheller Date: Mon, 28 Jul 2025 20:11:27 +0100 Subject: [PATCH] pico_status_led doxygen improvements --- .../pico_status_led/include/pico/status_led.h | 36 ++++++++++--------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/src/rp2_common/pico_status_led/include/pico/status_led.h b/src/rp2_common/pico_status_led/include/pico/status_led.h index 4b900d2bd..be7c0bd49 100644 --- a/src/rp2_common/pico_status_led/include/pico/status_led.h +++ b/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 */