From 273185b45aa6f9ec445b47faba688b6b7dbd3f66 Mon Sep 17 00:00:00 2001 From: Chen Wang Date: Fri, 10 Oct 2025 10:05:06 +0800 Subject: [PATCH] doxygen: fix two issues when building with doxygen 1.9.8 (#10768) * doxygen: remove @return command if function return void When doxygen is upgraded to v1.9.8 (on ubuntu 24.04), doxygen reports: "doxygen error: found documented return type for xxx that does not return anything" for those functions which return void but declare "@return" in doxygen comment. Solution: remove "@return" for those cases, and update guide document for how to write doxgen comment for functions. Signed-off-by: Chen Wang * doxygen: fixed a minor typo for uart doc This error is found when building with doxygen 1.9.8, but not detecetd on 1.9.1. Signed-off-by: Chen Wang --- components/drivers/audio/dev_audio.c | 4 ---- components/drivers/include/drivers/dev_can.h | 2 -- documentation/0.doxygen/example/src/function.c | 12 ++++++------ .../6.components/device-driver/uart/uart.md | 2 +- 4 files changed, 7 insertions(+), 13 deletions(-) diff --git a/components/drivers/audio/dev_audio.c b/components/drivers/audio/dev_audio.c index c4e806ca28..338ee67a0f 100644 --- a/components/drivers/audio/dev_audio.c +++ b/components/drivers/audio/dev_audio.c @@ -751,8 +751,6 @@ int rt_audio_samplerate_to_speed(rt_uint32_t bitValue) * See _audio_send_replay_frame for details * * @param[in] audio pointer to audio device - * - * @return void */ void rt_audio_tx_complete(struct rt_audio_device *audio) { @@ -768,8 +766,6 @@ void rt_audio_tx_complete(struct rt_audio_device *audio) * @param[in] pbuf pointer ro data to be received * * @param[in] len buffer size - * - * @return void */ void rt_audio_rx_done(struct rt_audio_device *audio, rt_uint8_t *pbuf, rt_size_t len) { diff --git a/components/drivers/include/drivers/dev_can.h b/components/drivers/include/drivers/dev_can.h index aa4878ee51..ef91302742 100644 --- a/components/drivers/include/drivers/dev_can.h +++ b/components/drivers/include/drivers/dev_can.h @@ -709,8 +709,6 @@ rt_err_t rt_hw_can_register(struct rt_can_device *can, * * @param[in] can A pointer to the CAN device structure. * @param[in] event The interrupt event mask, indicating the cause of the interrupt. - * - * @return void */ void rt_hw_can_isr(struct rt_can_device *can, int event); diff --git a/documentation/0.doxygen/example/src/function.c b/documentation/0.doxygen/example/src/function.c index 98b2007dea..96b30f7090 100644 --- a/documentation/0.doxygen/example/src/function.c +++ b/documentation/0.doxygen/example/src/function.c @@ -33,10 +33,12 @@ * * To documenting for functions, a comment block before the function * declaraion/definition is recommended to describe the general information - * of the function. In the comment block, a `@brief` is required, a `@return` - * is also required no matter if the function return values or not. `@param` is - * required if any, and if it is provided, direction [in]/[out]/[in,out] should - * be provide together. Other commands (such as `@note`) are optional. + * of the function. In the comment block, a `@brief` is required. A `@return` + * is also required if the function is intended to return a value, otherwise + * if the function is implemented with a void return type, `@return` is not + * required. `@param` is required if any, and if it is provided, + * direction [in]/[out]/[in,out] should be provide together. Other commands + * (such as `@note`) are optional. * * If you feel that the description of `@brief` is not enough, you * can add a detailed description part, which is also optional. @@ -72,8 +74,6 @@ * * @param[in] b Description of param b * - * @return void - * * @note This is a note for this structure, blah blah blah... */ void doxygen_example_func_foo(int a, int b) diff --git a/documentation/6.components/device-driver/uart/uart.md b/documentation/6.components/device-driver/uart/uart.md index 8f1784ced3..0a87440b71 100644 --- a/documentation/6.components/device-driver/uart/uart.md +++ b/documentation/6.components/device-driver/uart/uart.md @@ -86,7 +86,7 @@ There are three modes of uart data receiving and sending: interrupt mode, pollin The DMA (Direct Memory Access) transfer mode does not require the CPU to directly control the transfer, and does not have the process of reserving the scene and restoring the scene as they have in the interrupt processing mode. The DMA controller opens a path for directly transferring data to the RAM and the I/O device, which saves CPU resources to do other things. Using DMA transfer can continuously acquire or send a piece of information without taking up interrupts or delays, which is useful when communication is frequent or when large pieces of information are to be transmitted. ->RT_DEVICE_FLAG_STREAM: Stream mode is used to output a string to the serial terminal: when the output character is `"\n"` (corresponding to the hexadecimal value 0x0A), a ``\r"` is automatically output in front (corresponding to hexadecimal value is 0x0D). +> RT_DEVICE_FLAG_STREAM: Stream mode is used to output a string to the serial terminal: when the output character is `"\n"` (corresponding to the hexadecimal value 0x0A), a `"\r"` is automatically output in front (corresponding to hexadecimal value is 0x0D). The stream mode `RT_DEVICE_FLAG_STREAM` can be used with the receive and send mode parameter with the "|" logic.