Skip to content

include: zephyr: APIs doc: fix Doxygen \retval command usage #98324

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

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
+197 −197
Open

include: zephyr: APIs doc: fix Doxygen \retval command usage #98324

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b497b02
include: drivers: fix Doxygen \retval command usage
JarmouniA Oct 27, 2025
c1d25b2
include: bluetooth: fix Doxygen \retval command usage
JarmouniA Oct 27, 2025
12a7223
include: net: fix Doxygen \retval command usage
JarmouniA Oct 27, 2025
83cde8b
include: sys: fix Doxygen \retval command usage
JarmouniA Oct 27, 2025
2b61f08
include: kernel: fix Doxygen \retval command usage
JarmouniA Oct 27, 2025
2a5f222
include: fs: fix Doxygen \retval command usage
JarmouniA Oct 27, 2025
e78c800
include: zephyr: fix Doxygen \retval command usage
JarmouniA Oct 27, 2025
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
8 changes: 4 additions & 4 deletions include/zephyr/bluetooth/addr.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,8 +84,8 @@ static inline int bt_addr_cmp(const bt_addr_t *a, const bt_addr_t *b)

/** @brief Determine equality of two Bluetooth device addresses.
*
* @retval #true if the two addresses are equal
* @retval #false otherwise
* @retval true if the two addresses are equal
* @retval false otherwise
Comment on lines +87 to +88
Copy link
Contributor

@Thalley Thalley Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since you are already touching so many @retvals, consider if it makes sense to fully fix some of the issues with @retval in the documentation: #65974

E.g. these need to be

Suggested change
* @retval true if the two addresses are equal
* @retval false otherwise
* @retval true The two addresses are equal
* @retval false The two addresses are not equal

Copy link
Contributor Author

@JarmouniA JarmouniA Nov 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There was a 1st attempt in #97876, but closed it since the changes seemed to be somewhat controversial & it was going to take considerable time to address each case individually.

*/
static inline bool bt_addr_eq(const bt_addr_t *a, const bt_addr_t *b)
{
Expand All @@ -111,8 +111,8 @@ static inline int bt_addr_le_cmp(const bt_addr_le_t *a, const bt_addr_le_t *b)
* The Bluetooth LE addresses are equal if and only if both the types and
* the 48-bit addresses are numerically equal.
*
* @retval #true if the two addresses are equal
* @retval #false otherwise
* @retval true if the two addresses are equal
* @retval false otherwise
*/
static inline bool bt_addr_le_eq(const bt_addr_le_t *a, const bt_addr_le_t *b)
{
Expand Down
2 changes: 1 addition & 1 deletion include/zephyr/bluetooth/hci.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,7 +176,7 @@ int bt_hci_get_adv_sync_handle(const struct bt_le_per_adv_sync *sync, uint16_t *
*
* @param handle The periodic sync set handle
*
* @retval The corresponding periodic advertising sync set object on success,
* @return The corresponding periodic advertising sync set object on success,
* NULL if it does not exist.
*/
struct bt_le_per_adv_sync *bt_hci_per_adv_sync_lookup_handle(uint16_t handle);
Expand Down
4 changes: 2 additions & 2 deletions include/zephyr/canbus/isotp.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -275,7 +275,7 @@ void isotp_unbind(struct isotp_recv_ctx *rctx);
* @param len Size of the buffer.
* @param timeout Timeout for incoming data.
*
* @retval Number of bytes copied on success
* @return Number of bytes copied on success
* @retval ISOTP_RECV_TIMEOUT when "timeout" timed out
* @retval ISOTP_N_* on error
Comment on lines +278 to 280
Copy link
Contributor

@Thalley Thalley Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a bit curious to use both @return and @retval, but I guess it works:

Image

Although it may be better to have something like

Image (from e.g. https://man7.org/linux/man-pages/man2/send.2.html)

i.e. making it clear that it either returns a value, or a set of errors. I don't see anything in doxygen that supports this though - @kartben thoughts?

Copy link
Contributor

@kartben kartben Nov 5, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a bit curious to use both @return and @RetVal, but I guess it works

Yeah the combination of @return and @retval probably looks "wrong" at first sight, but I do think it's actually great. See here.

i.e. making it clear that it either returns a value, or a set of errors. I don't see anything in doxygen that supports this though - @kartben thoughts?

Yeah probably not supported. I think "Returns" vs. "Returns values" is already not so bad though?

Copy link
Contributor

@Thalley Thalley Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think "Returns" vs. "Returns values" is already not so bad though?

I don't think it is bad, I just think "Return Value" and "Errors" is better :)

*/
Expand All @@ -295,7 +295,7 @@ int isotp_recv(struct isotp_recv_ctx *rctx, uint8_t *data, size_t len, k_timeout
* @param buffer Pointer where the net_buf pointer is written to.
* @param timeout Timeout for incoming data.
*
* @retval Remaining data length for this transfer if BS > 0, 0 for BS = 0
* @return Remaining data length for this transfer if BS > 0, 0 for BS = 0
* @retval ISOTP_RECV_TIMEOUT when "timeout" timed out
* @retval ISOTP_N_* on error
*/
Expand Down
2 changes: 1 addition & 1 deletion include/zephyr/cpu_freq/cpu_freq.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ extern "C" {
* @param state Pointer to performance state.
*
*
* @retval 0 if request received successfully, -errno in case of failure.
* @return 0 if request received successfully, -errno in case of failure.
*/
int cpu_freq_pstate_set(const struct pstate *state);

Expand Down
2 changes: 1 addition & 1 deletion include/zephyr/cpu_freq/policy.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ extern "C" {
*
* @param pstate_out Pointer to the P-state struct where the next P-state is returned.
*
* @retval 0 in case of success, nonzero in case of failure.
* @return 0 in case of success, nonzero in case of failure.
*/
int cpu_freq_policy_select_pstate(const struct pstate **pstate_out);

Expand Down
4 changes: 2 additions & 2 deletions include/zephyr/debug/cpu_load.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,8 @@ void cpu_load_on_exit_idle(void);
*
* @param reset Reset the measurement after reading.
*
* @retval Positive number - CPU load in per mille.
* @retval Negative number - error code.
* @retval >=0 Positive number - CPU load in per mille.
* @retval <0 Negative number - error code.
*/
int cpu_load_get(bool reset);

Expand Down
4 changes: 2 additions & 2 deletions include/zephyr/debug/mipi_stp_decoder.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,7 +110,7 @@ struct mipi_stp_decoder_config {
* @param config Configuration.
*
* @retval 0 On successful initialization.
* @retval negative On failure.
* @retval <0 On failure.
*/
int mipi_stp_decoder_init(const struct mipi_stp_decoder_config *config);

Expand All @@ -122,7 +122,7 @@ int mipi_stp_decoder_init(const struct mipi_stp_decoder_config *config);
* @param len Data length.
*
* @retval 0 On successful decoding.
* @retval negative On failure.
* @retval <0 On failure.
*/
int mipi_stp_decoder_decode(const uint8_t *data, size_t len);

Expand Down
2 changes: 1 addition & 1 deletion include/zephyr/display/ssd16xx.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ enum ssd16xx_ram {
* @param desc Structure describing the buffer layout
* @param buf Output buffer
*
* @retval 0 on success, negative errno on failure.
* @return 0 on success, negative errno on failure.
*/
int ssd16xx_read_ram(const struct device *dev, enum ssd16xx_ram ram_type,
const uint16_t x, const uint16_t y,
Expand Down
2 changes: 1 addition & 1 deletion include/zephyr/drivers/adc.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1309,7 +1309,7 @@ static inline int adc_sequence_init_dt(const struct adc_dt_spec *spec,
*
* @param spec ADC specification from devicetree
*
* @retval true if the ADC device is ready for use and false otherwise.
* @return true if the ADC device is ready for use and false otherwise.
*/
static inline bool adc_is_ready_dt(const struct adc_dt_spec *spec)
{
Expand Down
8 changes: 4 additions & 4 deletions include/zephyr/drivers/can.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1002,7 +1002,7 @@ static inline const struct can_timing *z_impl_can_get_timing_data_max(const stru
* @param sample_pnt Sample point for the data phase in permille of the entire bit
* time or 0 for automatic sample point location.
*
* @retval 0 or positive sample point error on success.
* @return 0 or positive sample point error on success.
* @retval -EINVAL if the requested bitrate or sample point is out of range.
* @retval -ENOTSUP if the requested bitrate is not supported.
* @retval -EIO if @a can_get_core_clock() is not available.
Expand Down Expand Up @@ -1387,7 +1387,7 @@ static inline void z_impl_can_remove_rx_filter(const struct device *dev, int fil
* @param ide Get the maximum standard (11-bit) CAN ID filters if false, or extended (29-bit) CAN ID
* filters if true.
*
* @retval Positive number of maximum concurrent filters.
* @retval >=0 number of maximum concurrent filters.
* @retval -EIO General input/output error.
* @retval -ENOSYS If this function is not implemented by the driver.
*/
Expand Down Expand Up @@ -1684,7 +1684,7 @@ static inline uint32_t z_impl_can_stats_get_rx_overruns(const struct device *dev
*
* @param dlc Data Length Code (DLC).
*
* @retval Number of bytes.
* @return Number of bytes.
*/
static inline uint8_t can_dlc_to_bytes(uint8_t dlc)
{
Expand All @@ -1699,7 +1699,7 @@ static inline uint8_t can_dlc_to_bytes(uint8_t dlc)
*
* @param num_bytes Number of bytes.
*
* @retval Data Length Code (DLC).
* @return Data Length Code (DLC).
*/
static inline uint8_t can_bytes_to_dlc(uint8_t num_bytes)
{
Expand Down
12 changes: 6 additions & 6 deletions include/zephyr/drivers/cellular.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -237,7 +237,7 @@ __subsystem struct cellular_driver_api {
* @retval 0 if successful.
* @retval -EINVAL if any provided cellular network configuration is invalid or unsupported.
* @retval -ENOTSUP if API is not supported by cellular network device.
* @retval Negative errno-code otherwise.
* @retval <0 Negative errno-code otherwise.
Comment on lines 237 to +240
Copy link
Contributor

@Thalley Thalley Nov 5, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is also a bit weird where only a subset of the error codes are defined.

*/
static inline int cellular_configure_networks(const struct device *dev,
const struct cellular_network *networks, uint8_t size)
Expand All @@ -260,7 +260,7 @@ static inline int cellular_configure_networks(const struct device *dev,
*
* @retval 0 if successful.
* @retval -ENOTSUP if API is not supported by cellular network device.
* @retval Negative errno-code otherwise.
* @retval <0 Negative errno-code otherwise.
*/
static inline int cellular_get_supported_networks(const struct device *dev,
const struct cellular_network **networks,
Expand All @@ -285,7 +285,7 @@ static inline int cellular_get_supported_networks(const struct device *dev,
* @retval 0 if successful.
* @retval -ENOTSUP if API is not supported by cellular network device.
* @retval -ENODATA if device is not in a state where signal can be polled
* @retval Negative errno-code otherwise.
* @retval <0 Negative errno-code otherwise.
*/
static inline int cellular_get_signal(const struct device *dev,
const enum cellular_signal_type type, int16_t *value)
Expand All @@ -310,7 +310,7 @@ static inline int cellular_get_signal(const struct device *dev,
* @retval 0 if successful.
* @retval -ENOTSUP if API is not supported by cellular network device.
* @retval -ENODATA if modem does not provide info requested
* @retval Negative errno-code from chat module otherwise.
* @retval <0 Negative errno-code from chat module otherwise.
*/
static inline int cellular_get_modem_info(const struct device *dev,
const enum cellular_modem_info_type type, char *info,
Expand All @@ -335,7 +335,7 @@ static inline int cellular_get_modem_info(const struct device *dev,
* @retval 0 if successful.
* @retval -ENOSYS if API is not supported by cellular network device.
* @retval -ENODATA if modem does not provide info requested
* @retval Negative errno-code from chat module otherwise.
* @retval <0 Negative errno-code from chat module otherwise.
*/
static inline int cellular_get_registration_status(const struct device *dev,
enum cellular_access_technology tech,
Expand Down Expand Up @@ -364,7 +364,7 @@ static inline int cellular_get_registration_status(const struct device *dev,
* @retval -EINVAL if APN string invalid or too long.
* @retval -EALREADY if APN identical to current one, nothing to do
* @retval -EBUSY if modem is already dialled, APN cannot be changed
* @retval Negative errno-code otherwise.
* @retval <0 Negative errno-code otherwise.
*/
static inline int cellular_set_apn(const struct device *dev, const char *apn)
{
Expand Down
4 changes: 2 additions & 2 deletions include/zephyr/drivers/charger.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -376,7 +376,7 @@ __subsystem struct charger_driver_api {
* @param val Pointer to charger_propval union
*
* @retval 0 if successful
* @retval < 0 if getting property failed
* @retval <0 if getting property failed
*/
__syscall int charger_get_prop(const struct device *dev, const charger_prop_t prop,
union charger_propval *val);
Expand All @@ -397,7 +397,7 @@ static inline int z_impl_charger_get_prop(const struct device *dev, const charge
* @param val Pointer to charger_propval union
*
* @retval 0 if successful
* @retval < 0 if setting property failed
* @retval <0 if setting property failed
*/
__syscall int charger_set_prop(const struct device *dev, const charger_prop_t prop,
const union charger_propval *val);
Expand Down
4 changes: 2 additions & 2 deletions include/zephyr/drivers/clock_control.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -174,7 +174,7 @@ static inline int clock_control_off(const struct device *dev,
* @retval -EALREADY if clock was already started and is starting or running.
* @retval -ENOTSUP If the requested mode of operation is not supported.
* @retval -ENOSYS if the interface is not implemented.
* @retval other negative errno on vendor specific error.
* @retval <0 other negative errno on vendor specific error.
*/
static inline int clock_control_async_on(const struct device *dev,
clock_control_subsys_t sys,
Expand Down Expand Up @@ -252,7 +252,7 @@ static inline int clock_control_get_rate(const struct device *dev,
* @retval -EALREADY if clock was already in the given rate.
* @retval -ENOTSUP If the requested mode of operation is not supported.
* @retval -ENOSYS if the interface is not implemented.
* @retval other negative errno on vendor specific error.
* @retval <0 other negative errno on vendor specific error.
*/
static inline int clock_control_set_rate(const struct device *dev,
clock_control_subsys_t sys,
Expand Down
6 changes: 3 additions & 3 deletions include/zephyr/drivers/counter.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -377,7 +377,7 @@ static inline uint32_t z_impl_counter_get_max_top_value(const struct device *dev
* @param dev Pointer to the device structure for the driver instance.
*
* @retval 0 If successful.
* @retval Negative errno code if failure.
* @retval <0 Negative errno code if failure.
*/
__syscall int counter_start(const struct device *dev);

Expand Down Expand Up @@ -414,7 +414,7 @@ static inline int z_impl_counter_stop(const struct device *dev)
* @param ticks Pointer to where to store the current counter value
*
* @retval 0 If successful.
* @retval Negative error code on failure getting the counter value
* @retval <0 Negative error code on failure getting the counter value
*/
__syscall int counter_get_value(const struct device *dev, uint32_t *ticks);

Expand All @@ -433,7 +433,7 @@ static inline int z_impl_counter_get_value(const struct device *dev,
* @param ticks Pointer to where to store the current counter value
*
* @retval 0 If successful.
* @retval Negative error code on failure getting the counter value
* @retval <0 Negative error code on failure getting the counter value
*/
__syscall int counter_get_value_64(const struct device *dev, uint64_t *ticks);

Expand Down
6 changes: 3 additions & 3 deletions include/zephyr/drivers/dai.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -410,7 +410,7 @@ static inline int dai_config_set(const struct device *dev,
* @param dev Pointer to the device structure for the driver instance
* @param cfg Pointer to the config structure to be filled by the instance
* @param dir Stream direction: RX or TX as defined by DAI_DIR_*
* @retval 0 if success, negative if invalid parameters or DAI un-configured
* @return 0 if success, negative if invalid parameters or DAI un-configured
*/
static inline int dai_config_get(const struct device *dev,
struct dai_config *cfg,
Expand All @@ -428,7 +428,7 @@ static inline int dai_config_get(const struct device *dev,
* @param dir Stream direction: RX or TX as defined by DAI_DIR_*
* @param stream_id Stream id: some drivers may have stream specific
* properties, this id specifies the stream.
* @retval Pointer to the structure containing properties,
* @return Pointer to the structure containing properties,
* or NULL if error or no properties
*/
static inline const struct dai_properties *dai_get_properties(const struct device *dev,
Expand Down Expand Up @@ -565,7 +565,7 @@ static inline int dai_ts_get(const struct device *dev, struct dai_ts_cfg *cfg,
*
* @retval 0 If successful.
* @retval -ENOSYS If the configuration update operation is not implemented.
* @retval Negative errno code if failure.
* @retval <0 Negative errno code if failure.
*/
static inline int dai_config_update(const struct device *dev,
const void *bespoke_cfg,
Expand Down
20 changes: 10 additions & 10 deletions include/zephyr/drivers/display.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -275,7 +275,7 @@ __subsystem struct display_driver_api {
* @param desc Pointer to a structure describing the buffer layout
* @param buf Pointer to buffer array
*
* @retval 0 on success else negative errno code.
* @return 0 on success else negative errno code.
*/
static inline int display_write(const struct device *dev, const uint16_t x,
const uint16_t y,
Expand All @@ -297,7 +297,7 @@ static inline int display_write(const struct device *dev, const uint16_t x,
* @param desc Pointer to a structure describing the buffer layout
* @param buf Pointer to buffer array
*
* @retval 0 on success else negative errno code.
* @return 0 on success else negative errno code.
* @retval -ENOSYS if not implemented.
*/
static inline int display_read(const struct device *dev, const uint16_t x,
Expand All @@ -320,7 +320,7 @@ static inline int display_read(const struct device *dev, const uint16_t x,
*
* @param dev Pointer to device structure
*
* @retval 0 on success else negative errno code.
* @return 0 on success else negative errno code.
* @retval -ENOSYS if not implemented.
*/
static inline int display_clear(const struct device *dev)
Expand All @@ -340,7 +340,7 @@ static inline int display_clear(const struct device *dev)
*
* @param dev Pointer to device structure
*
* @retval Pointer to frame buffer or NULL if direct framebuffer access
* @return Pointer to frame buffer or NULL if direct framebuffer access
* is not supported
*
*/
Expand Down Expand Up @@ -372,7 +372,7 @@ static inline void *display_get_framebuffer(const struct device *dev)
*
* @param dev Pointer to device structure
*
* @retval 0 on success else negative errno code.
* @return 0 on success else negative errno code.
* @retval -ENOSYS if not implemented.
*/
static inline int display_blanking_on(const struct device *dev)
Expand All @@ -396,7 +396,7 @@ static inline int display_blanking_on(const struct device *dev)
*
* @param dev Pointer to device structure
*
* @retval 0 on success else negative errno code.
* @return 0 on success else negative errno code.
* @retval -ENOSYS if not implemented.
*/
static inline int display_blanking_off(const struct device *dev)
Expand All @@ -420,7 +420,7 @@ static inline int display_blanking_off(const struct device *dev)
* @param dev Pointer to device structure
* @param brightness Brightness in steps of 1/256
*
* @retval 0 on success else negative errno code.
* @return 0 on success else negative errno code.
* @retval -ENOSYS if not implemented.
*/
static inline int display_set_brightness(const struct device *dev,
Expand All @@ -445,7 +445,7 @@ static inline int display_set_brightness(const struct device *dev,
* @param dev Pointer to device structure
* @param contrast Contrast in steps of 1/256
*
* @retval 0 on success else negative errno code.
* @return 0 on success else negative errno code.
* @retval -ENOSYS if not implemented.
*/
static inline int display_set_contrast(const struct device *dev, uint8_t contrast)
Expand Down Expand Up @@ -482,7 +482,7 @@ static inline void display_get_capabilities(const struct device *dev,
* @param dev Pointer to device structure
* @param pixel_format Pixel format to be used by display
*
* @retval 0 on success else negative errno code.
* @return 0 on success else negative errno code.
* @retval -ENOSYS if not implemented.
*/
static inline int
Expand All @@ -505,7 +505,7 @@ display_set_pixel_format(const struct device *dev,
* @param dev Pointer to device structure
* @param orientation Orientation to be used by display
*
* @retval 0 on success else negative errno code.
* @return 0 on success else negative errno code.
* @retval -ENOSYS if not implemented.
*/
static inline int display_set_orientation(const struct device *dev,
Expand Down
Loading
Loading