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 <unicorn_wang@outlook.com>

* 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 <unicorn_wang@outlook.com>

Author: unicornx

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)
 {

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);
 

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)

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.