[Feature] doxygen的audio注释中剩余问题汇总

[1078249029]

Describe problem solved by the proposed feature

目前在编写audio注释时遇到了如下问题

首先是源代码的问题
@BernardXiong

1. 根据 [Bug] audio 的 API doxygen 注释中的问题 #10065 rt_audio_samplerate_to_speed可能是个无用函数，在bsp内也没有使用到，这个函数是否应该删除？如果确实要删除的话，内部负责采样率的宏AUDIO_SAMP_RATE_xxK是否也应删除？
2. 目前audio模块的内部api有许多无效返回值和参数，这些是否需要在doxygen文档编写后统一修改？例如对于rt_audio_pipe_read的pos参数是无用的，rt_audio_tx_complete并没有检查_audio_send_replay_frame错误码，以及_audio_dev_close永远返回RT_EOK`

之后是注释格式化的问题
@unicornx

1. 对于宏来说，注释可以位于宏右侧也可以位于宏上方，这点是否应该规定下？或者推荐使用哪种格式？
2. 对于拥有多行注释的参数或者其他doxygen元素，注释写法有多种：
   类似@brief这种

/**
 * @brief Send a replay frame to the audio hardware device
 *
 * This function handles sending audio data from the memory queue to the hardware buffer for playback.
 * If there is no data available in the queue, it sends zero frames. Otherwise, it copies data from the memory pool
 * to the hardware device FIFO and manages the read index and position accordingly.
 *
 * @param[in] 
 * 
 * Audio pointer to the audio device structure.This is a section of comments, which is very long
 * for showing effect of multilines comments.
 *
 * @return error code, RT_EOK is successful otherwise means failure
 *
 * @note 
 * 
 * This function may temporarily disable interrupts or perform time-consuming operations like memcpy,            
 * which could affect system responsiveness
 */

分行并缩进保留*

/**
 * @brief Send a replay frame to the audio hardware device
 *
 * This function handles sending audio data from the memory queue to the hardware buffer for playback.
 * If there is no data available in the queue, it sends zero frames. Otherwise, it copies data from the memory pool
 * to the hardware device FIFO and manages the read index and position accordingly.
 *
 * @param[in] audio pointer to the audio device structure.This is a section of comments, which is very long
 *                     for showing effect of multilines comments.
 *
 * @return error code, RT_EOK is successful otherwise means failure
 *
 * @note This function may temporarily disable interrupts or perform time-consuming operations like memcpy,
 *             which could affect system responsiveness
 */

不保留*

/**
 * @brief Send a replay frame to the audio hardware device
 *
 * This function handles sending audio data from the memory queue to the hardware buffer for playback.
 * If there is no data available in the queue, it sends zero frames. Otherwise, it copies data from the memory pool
 * to the hardware device FIFO and manages the read index and position accordingly.
 *
 * @param[in] audio pointer to the audio device structure.This is a section of comments, which is very long
                      for showing effect of multilines comments.
 *
 * @return error code, RT_EOK is successful otherwise means failure
 *
 * @note This function may temporarily disable interrupts or perform time-consuming operations like memcpy,
               which could affect system responsiveness
 */

上面三种情况生成的网页效果均相同，差别只在源代码浏览上，这点是否需要统一起来？

Describe your preferred solution

No response

Describe possible alternatives

No response

[unicornx]

• 对于宏来说，注释可以位于宏右侧也可以位于宏上方，这点是否应该规定下？或者推荐使用哪种格式？

目前对于非函数形式的宏推荐的注释是放在后面，考虑到一般这种情况的宏不会很长，所以后面再加注释也不会很长。如果真的很长情况出现，当然也是可以放在宏上方，这个可以补充说明一下。已经提了 #10097，我会找个时间补一下。

• 对于拥有多行注释的参数或者其他doxygen元素，注释写法有多种：

这个我觉得就不用规定那么细致了，即使 howto 里写了也很难强制检查。所以这个我觉得就靠作者自己的审美以及 reviewer 的检查和提醒吧。无伤大雅。
顺便说一下，你说的第三种方式我觉得是不推荐的，大部分作者不会这么做的，除非是不小心，那就靠 reviewer 保证了。