Skip to content

pico_status_led doxygen improvements #2601

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 28, 2025
Merged

pico_status_led doxygen improvements #2601

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 19 additions & 17 deletions src/rp2_common/pico_status_led/include/pico/status_led.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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))
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
*/
Expand All @@ -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
Expand All @@ -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
*/
Expand All @@ -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
*/
Expand All @@ -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
Expand All @@ -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
*/
Expand Down
Loading