From 7138846dbe63b33db6868f33512e25d91bb5f2be Mon Sep 17 00:00:00 2001 From: Chen Wang Date: Thu, 9 Oct 2025 13:54:16 +0800 Subject: [PATCH 1/2] 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 --- components/drivers/audio/dev_audio.c | 4 ---- components/drivers/include/drivers/dev_can.h | 2 -- documentation/0.doxygen/example/src/function.c | 12 ++++++------ 3 files changed, 6 insertions(+), 12 deletions(-) diff --git a/components/drivers/audio/dev_audio.c b/components/drivers/audio/dev_audio.c index c4e806ca284..338ee67a0fc 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 aa4878ee514..ef91302742c 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 98b2007deae..96b30f7090d 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) From d63e42c88ca858c053f625c685822a85266c8550 Mon Sep 17 00:00:00 2001 From: Chen Wang Date: Thu, 9 Oct 2025 14:59:31 +0800 Subject: [PATCH 2/2] 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 --- documentation/6.components/device-driver/uart/uart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/6.components/device-driver/uart/uart.md b/documentation/6.components/device-driver/uart/uart.md index 8f1784ced3c..0a87440b71a 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.