Repository: RT-Thread/rt-thread
Pull request #10073: [doxygen][audio] Fix doxygen comments for audio component
Author: login: 1078249029
Labels: name: Doc
description: This PR/issue related with documents
name: Component
name: component: drivers/audio
name: component: drivers
Created: 2025-03-04T12:41:47Z | Merged: 2025-03-06T03:45:07Z

Added comments for data structure and rt_audio_ops in dev_audio.h. Enriched comments for macro group. Moved and renamed folder audio.

## 拉取/合并请求描述：(PR description)

[
<!-- 这段方括号里的内容是您**必须填写并替换掉**的，否则PR不可能被合并。**方括号外面的内容不需要修改，但请仔细阅读。**
The content in this square bracket must be filled in and replaced, otherwise, PR can not be merged. The contents outside square brackets need not be changed, but please read them carefully.

请在这里填写您的PR描述，可以包括以下之一的内容：为什么提交这份PR；解决的问题是什么，你的解决方案是什么；
Please fill in your PR description here, which can include one of the following items: why to submit this PR; what is the problem solved and what is your solution;

并确认并列出已经在什么情况或板卡上进行了测试。
And confirm in which case or board has been tested. -->

#### 为什么提交这份PR (why to submit this PR)
#10065 

#### 你的解决方案是什么 (what is your solution)



#### 请提供验证的bsp和config (provide the config and bsp) 

<!-- 请填写验证bsp目录下面的目录比如bsp/stm32/stm32l496-st-nucleo

Please provide the path of verfied bsp. Like bsp/stm32/stm32l496-st-nucleo  bsp/ESP32_C3 -->

- BSP:

<!-- 请填写.config 文件中需要改动的config

Please provide the changed config of .config file to how to verify the PR file like CONFIG_BSP_USING_I2C CONFIG_BSP_USING_WDT -->

- .config:

<!-- 请提供自己仓库的PR branch的action的编译链接相关PR文件成功的链接：

Please provide the link of action triggered by your own repo's action  

https://github.com/RT-Thread/rt-thread/actions/workflows/manual_dist.yml -->

- action:

]

<!-- 以下的内容不应该在提交PR时的message修改，修改下述message，PR会被直接关闭。请在提交PR后，浏览器查看PR并对以下检查项逐项check，没问题后逐条在页面上打钩。
The following content must not be changed in the submitted PR message. Otherwise, the PR will be closed immediately. After submitted PR, please use a web browser to visit PR, and check items one by one, and ticked them if no problem. -->

### 当前拉取/合并请求的状态 Intent for your PR

必须选择一项 Choose one (Mandatory):

- [ ] 本拉取/合并请求是一个草稿版本 This PR is for a code-review and is intended to get feedback
- [x] 本拉取/合并请求是一个成熟版本 This PR is mature, and ready to be integrated into the repo

### 代码质量 Code Quality：

我在这个拉取/合并请求中已经考虑了 As part of this pull request, I've considered the following:

- [x] 已经仔细查看过代码改动的对比 Already check the difference between PR and old code
- [x] 代码风格正确，包括缩进空格，命名及其他风格 Style guide is adhered to, including spacing, naming and other styles
- [ ] 没有垃圾代码，代码尽量精简，不包含`#if 0`代码，不包含已经被注释了的代码 All redundant code is removed and cleaned up
- [x] 所有变更均有原因及合理的，并且不会影响到其他软件组件代码或BSP All modifications are justified and not affect other components or BSP
- [x] 对难懂代码均提供对应的注释 I've commented appropriately where code is tricky
- [ ] 代码是高质量的 Code in this PR is of high quality
- [x] 已经使用[formatting](https://github.com/mysterywolf/formatting) 等源码格式化工具确保格式符合[RT-Thread代码规范](https://github.com/RT-Thread/rt-thread/blob/master/documentation/contribution_guide/coding_style_cn.md) This PR complies with [RT-Thread code specification](https://github.com/RT-Thread/rt-thread/blob/master/documentation/contribution_guide/coding_style_en.md)
- [ ] 如果是新增bsp, 已经添加ci检查到[.github/workflows/bsp_buildings.yml](workflows/bsp_buildings.yml)  详细请参考链接[BSP自查](https://www.rt-thread.org/document/site/#/rt-thread-version/rt-thread-standard/development-guide/bsp-selfcheck/bsp_selfcheck)



Diff:
diff --git a/components/drivers/audio/dev_audio.c b/components/drivers/audio/dev_audio.c
index fd5bc472060..64e847a1fd9 100644
--- a/components/drivers/audio/dev_audio.c
+++ b/components/drivers/audio/dev_audio.c
@@ -7,6 +7,7 @@
  * Date           Author       Notes
  * 2017-05-09     Urey         first version
  * 2019-07-09     Zero-Free    improve device ops interface and data flows
+ * 2025-03-04     wumingzi     add doxygen comments.
  */
 
 #include <stdio.h>
@@ -23,7 +24,7 @@
 #endif
 
 /**
- * @addtogroup group_AudioPipe
+ * @addtogroup group_Audio
  */
 
 /** @{ */
diff --git a/components/drivers/audio/dev_audio_pipe.c b/components/drivers/audio/dev_audio_pipe.c
index 80f671b8c2f..686b053c1e3 100644
--- a/components/drivers/audio/dev_audio_pipe.c
+++ b/components/drivers/audio/dev_audio_pipe.c
@@ -6,6 +6,7 @@
  * Change Logs:
  * Date           Author       Notes
  * 2012-09-30     Bernard      first version.
+ * 2025-03-04     wumingzi     add doxygen comments.
  */
 
 #include <rthw.h>
diff --git a/components/drivers/audio/dev_audio_pipe.h b/components/drivers/audio/dev_audio_pipe.h
index 5050c7baa89..af7c5071096 100644
--- a/components/drivers/audio/dev_audio_pipe.h
+++ b/components/drivers/audio/dev_audio_pipe.h
@@ -5,6 +5,7 @@
  *
  * Change Logs:
  * Date           Author       Notes
+ * 2025-03-04     wumingzi     add doxygen comments.
  */
 #ifndef __DEV_AUDIO_PIPE_H__
 #define __DEV_AUDIO_PIPE_H__
diff --git a/components/drivers/include/drivers/dev_audio.h b/components/drivers/include/drivers/dev_audio.h
index 9d9e1af6325..b9e9f7055c2 100644
--- a/components/drivers/include/drivers/dev_audio.h
+++ b/components/drivers/include/drivers/dev_audio.h
@@ -7,7 +7,7 @@
  * Date           Author       Notes
  * 2017-05-09     Urey         first version
  * 2019-07-09     Zero-Free    improve device ops interface and data flows
- *
+ * 2025-03-04     wumingzi     add doxygen comments.
  */
 
 #ifndef __DEV_AUDIO_H__
@@ -21,10 +21,7 @@
  * @ingroup group_Drivers RT-Thread Drivers
  *
  * @brief Audio driver API.
- */
-
-/**
- * @addtogroup group_Audio
+ *
  * @{
  */
 
@@ -32,10 +29,7 @@
  * @defgroup audio_control AUDIO_CTL
  *
  * @brief Control audio device.
- */
-
-/**
- * @addtogroup audio_control
+ *
  * @{
  */
 
@@ -54,32 +48,26 @@
 #define AUDIO_CTL_STOP                      _AUDIO_CTL(4) /**< Stop audio device */
 #define AUDIO_CTL_GETBUFFERINFO             _AUDIO_CTL(5) /**< Get audio device buffer information */
 
-/** @} */ /* End of audio_control*/
+/** @} */ /* End of audio_control */
 
 /**
  * @defgroup audio_type AUDIO_TYPE
  *
  * @brief Audio Device Types
- */
-
-/**
- * @addtogroup audio_type
+ *
  * @{
  */
 #define AUDIO_TYPE_QUERY                    0x00 /**< Query audio device type */
 #define AUDIO_TYPE_INPUT                    0x01 /**< Set audio device type to input type */
 #define AUDIO_TYPE_OUTPUT                   0x02 /**< Set audio device type to output type */
 #define AUDIO_TYPE_MIXER                    0x04 /**< Set audio device type to mixer type */
-/** @} */ /* End of audio_type*/
+/** @} */ /* End of audio_type */
 
 /**
  * @defgroup audio_samp_rates AUDIO_SAMP_RATES
  *
  * @brief Supported audio sample rates for the audio device.
- */
-
-/**
- * @addtogroup audio_samp_rates
+ *
  * @{
  */
 #define AUDIO_SAMP_RATE_8K                  0x0001 /**< Set audio device sample rate to 8K */
@@ -94,16 +82,13 @@
 #define AUDIO_SAMP_RATE_160K                0x0200 /**< Set audio device sample rate to 160K */
 #define AUDIO_SAMP_RATE_172K                0x0400 /**< Set audio device sample rate to 172K */
 #define AUDIO_SAMP_RATE_192K                0x0800 /**< Set audio device sample rate to 192K */
-/** @} */ /* End of audio_samp_rates*/
+/** @} */ /* End of audio_samp_rates */
 
 /**
  * @defgroup audio_bit_rates AUDIO_BIT_RATES
  *
  * @brief Supported bit rates for the audio device.
- */
-
-/**
- * @addtogroup audio_bit_rates
+ *
  * @{
  */
 #define AUDIO_BIT_RATE_22K                  0x01 /**< Set audio device bit rates to 22K */
@@ -114,40 +99,36 @@
 #define AUDIO_BIT_RATE_160K                 0x20 /**< Set audio device bit rates to 160K */
 #define AUDIO_BIT_RATE_172K                 0x40 /**< Set audio device bit rates to 172K */
 #define AUDIO_BIT_RATE_192K                 0x80 /**< Set audio device bit rates to 192K */
-/** @} */ /* End of audio_bit_rates*/
+/** @} */ /* End of audio_bit_rates */
 
 
 /**
  * @defgroup audio_dsp AUDIO_DSP
  *
- * @brief Support Dsp(input/output) Units controls
- */
-
-/**
- * @addtogroup audio_dsp
+ * @brief Support Dsp(input/output) Units controls. The macro group from application level, can
+ *        set audio mixer parameters including samplerate, channels etc.
+ *
  * @{
  */
 #define AUDIO_DSP_PARAM                     0 /**< get/set all params */
 #define AUDIO_DSP_SAMPLERATE                1 /**< samplerate */
 #define AUDIO_DSP_CHANNELS                  2 /**< channels */
 #define AUDIO_DSP_SAMPLEBITS                3 /**< sample bits width */
-/** @} */ /* End of audio_dsp*/
+/** @} */ /* End of audio_dsp */
 
 /**
  * @defgroup audio_mixer AUDIO_MIXER
  *
- * @brief Supported Mixer Units controls
- */
-
-/**
- * @addtogroup audio_mixer
+ * @brief Supported Mixer Units controls. The macro group from driver level, can set audio mixer
+ *        parameters including volume, frequence db, microphone etc.
+ *
  * @{
  */
 #define AUDIO_MIXER_QUERY                   0x0000 /**< Query mixer capabilities */
 #define AUDIO_MIXER_MUTE                    0x0001 /**< Mute audio device */
 #define AUDIO_MIXER_VOLUME                  0x0002 /**< Set mixer volume */
 #define AUDIO_MIXER_BASS                    0x0004 /**< Set the low-frequency section of the mixer */
-#define AUDIO_MIXER_MID                     0x0008 /**< Set the mid-frequency section of the mixer*/
+#define AUDIO_MIXER_MID                     0x0008 /**< Set the mid-frequency section of the mixer */
 #define AUDIO_MIXER_TREBLE                  0x0010 /**< Set the high-frequency section of the mixer */
 #define AUDIO_MIXER_EQUALIZER               0x0020 /**< Set equalizer option */
 #define AUDIO_MIXER_LINE                    0x0040 /**< Set line control option */
@@ -155,7 +136,7 @@
 #define AUDIO_MIXER_MIC                     0x0100 /**< Set microphone option */
 #define AUDIO_MIXER_VITURAL                 0x0200 /**< Set virtual audio option */
 #define AUDIO_MIXER_EXTEND                  0x8000 /**< Extend mixer command */
-/** @} */ /* End of audio_mixer*/
+/** @} */ /* End of audio_mixer */
 
 #define AUDIO_VOLUME_MAX                    (100)
 #define AUDIO_VOLUME_MIN                    (0)
@@ -181,24 +162,35 @@ enum
  */
 struct rt_audio_buf_info
 {
-    rt_uint8_t *buffer;
-    rt_uint16_t block_size;
-    rt_uint16_t block_count;
-    rt_uint32_t total_size;
+    rt_uint8_t *buffer;         /**< Audio buffer information */
+    rt_uint16_t block_size;     /**< Audio block_size information for replay function */
+    rt_uint16_t block_count;    /**< Audio block_count information for replay function */
+    rt_uint32_t total_size;     /**< Audio total_size which is equal to block_size multiplying
+                                 *   block_count information for replay function */
 };
 
 struct rt_audio_device;
 struct rt_audio_caps;
 struct rt_audio_configure;
+
+/**
+ * @brief Aduio device operators
+ */
 struct rt_audio_ops
 {
+    /** Get audio capabilities information */
     rt_err_t (*getcaps)(struct rt_audio_device *audio, struct rt_audio_caps *caps);
+    /** Configure audio devices */
     rt_err_t (*configure)(struct rt_audio_device *audio, struct rt_audio_caps *caps);
+    /** Initialize audio device */
     rt_err_t (*init)(struct rt_audio_device *audio);
+    /** Turn on the audio device */
     rt_err_t (*start)(struct rt_audio_device *audio, int stream);
+    /** Turn off the audio device */
     rt_err_t (*stop)(struct rt_audio_device *audio, int stream);
+    /** Transmit data between application and device */
     rt_ssize_t (*transmit)(struct rt_audio_device *audio, const void *writeBuf, void *readBuf, rt_size_t size);
-    /* get page size of codec or private buffer's info */
+    /** Get page size of codec or private buffer's info */
     void (*buffer_info)(struct rt_audio_device *audio, struct rt_audio_buf_info *info);
 };
 
@@ -211,9 +203,9 @@ struct rt_audio_ops
  */
 struct rt_audio_configure
 {
-    rt_uint32_t samplerate;
-    rt_uint16_t channels;
-    rt_uint16_t samplebits;
+    rt_uint32_t samplerate; /**< Audio samplerate information */
+    rt_uint16_t channels;   /**< Audio channels information */
+    rt_uint16_t samplebits; /**< Audio samplebits information */
 };
 
 /**
@@ -221,15 +213,15 @@ struct rt_audio_configure
  */
 struct rt_audio_caps
 {
-    int main_type;
-    int sub_type;
+    int main_type;                          /**< Audio main type, one value of @ref audio_type */
+    int sub_type;                           /**< Audio sub type, one value of @ref audio_dsp @ref audio_mixer */
 
     union
     {
-        rt_uint32_t mask;
-        int     value;
-        struct rt_audio_configure config;
-    } udata;
+        rt_uint32_t mask;                   /**< Capabilities mask */
+        int     value;                      /**< Capabilities value */
+        struct rt_audio_configure config;   /**< Audio samplebits information */
+    } udata;                                /**< User data */
 };
 
 /**
@@ -237,17 +229,19 @@ struct rt_audio_caps
  */
 struct rt_audio_replay
 {
-    struct rt_mempool *mp;
-    struct rt_data_queue queue;
-    struct rt_mutex lock;
-    struct rt_completion cmp;
-    struct rt_audio_buf_info buf_info;
-    rt_uint8_t *write_data;
-    rt_uint16_t write_index;
-    rt_uint16_t read_index;
-    rt_uint32_t pos;
-    rt_uint8_t event;
-    rt_bool_t activated;
+    struct rt_mempool *mp;              /**< Memory pool for audio replay */
+    struct rt_data_queue queue;         /**< Replay data queue */
+    struct rt_mutex lock;               /**< Replay mutex lock */
+    struct rt_completion cmp;           /**< Replay completion, it will be */
+    struct rt_audio_buf_info buf_info;  /**< Replay buffer information */
+    rt_uint8_t *write_data;             /**< Pointer to the data to be written into data queue */
+    rt_uint16_t write_index;            /**< Index of pointer write_data.It records how much data
+                                         *   has been written in currently being played block */
+    rt_uint16_t read_index;             /**< Index of replaying data for audio device, it indicates index
+                                         *   of replay in the blocks which is currently being played */
+    rt_uint32_t pos;                    /**< Global position of audio replay */
+    rt_uint8_t event;                   /**< Event flag */
+    rt_bool_t activated;                /**< Activaty flag */
 };
 
 /**
@@ -264,10 +258,10 @@ struct rt_audio_record
  */
 struct rt_audio_device
 {
-    struct rt_device           parent;
-    struct rt_audio_ops        *ops;
-    struct rt_audio_replay     *replay;
-    struct rt_audio_record     *record;
+    struct rt_device           parent;  /**< Audio device parents */
+    struct rt_audio_ops        *ops;    /**< Audio device operator */
+    struct rt_audio_replay     *replay; /**< Pointer to audio replay structure */
+    struct rt_audio_record     *record; /**< Pointer to audio record structure */
 };
 
 rt_err_t    rt_audio_register(struct rt_audio_device *audio, const char *name, rt_uint32_t flag, void *data);
@@ -277,11 +271,9 @@ void        rt_audio_rx_done(struct rt_audio_device *audio, rt_uint8_t *pbuf, rt
 /**
  * @defgroup audio_codec_cmd CODEC_CMD
  *
- * @brief Device Control Commands
- */
-
-/**
- * @addtogroup audio_codec_cmd
+ * @brief Device Control Commands. The macro group from hardware level, can set codec
+ *        parametes including volume, EQ and 3D etc.
+ *
  * @{
  */
 #define CODEC_CMD_RESET             0 /**< Reset audio device by codec */
@@ -292,7 +284,7 @@ void        rt_audio_rx_done(struct rt_audio_device *audio, rt_uint8_t *pbuf, rt
 #define CODEC_CMD_3D                5 /**< Set 3D effect by codec */
 
 #define CODEC_VOLUME_MAX            (63)
-/** @} */ /* End of audio_codec_cmd*/
+/** @} */ /* End of audio_codec_cmd */
 
 /** @} group_Audio */
 
diff --git a/documentation/device/adudio/audio.md b/documentation/5.device/audio/audio.md
similarity index 100%
rename from documentation/device/adudio/audio.md
rename to documentation/5.device/audio/audio.md


Reviews:
user: login: unicornx
body: commit message 一行不要太长，80 列左右就可以回车换行了。
state: CHANGES_REQUESTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-05T01:20:56Z
user: login: unicornx
body: 就把下面提的对齐问题处理一下吧，其他没有了，你再改一下，我就 approve 了。

宏分组的方法挺好的，以后值得推广。我会提个 pr 补充到 how to 里面去

callback 的写法我也会另外提个 pr 补充到 howto 里面去。

Thanks，
Chen
state: CHANGES_REQUESTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-06T00:45:13Z
user: login: 1078249029
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-06T01:24:58Z
user: login: unicornx
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-06T01:27:09Z
user: login: unicornx
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-06T03:21:16Z
user: login: Rbb666
state: APPROVED
author_association: MEMBER
submitted_at: 2025-03-06T03:44:52Z

Review comments:
path: components/drivers/include/drivers/dev_audio.h
user: login: unicornx
body: 文字和 ”*/“ 之间要加空格，譬如下面 ”audio_control“ 后面缺个空格：

```c
/** @} */ /* End of audio_control*/
```

这样的地方有好几处，请搜索并改正。


created_at: 2025-03-05T00:32:06Z
author_association: CONTRIBUTOR
diff_hunk: @@ -181,25 +183,30 @@ enum
  */
 struct rt_audio_buf_info
 {
-    rt_uint8_t *buffer;
-    rt_uint16_t block_size;
-    rt_uint16_t block_count;
-    rt_uint32_t total_size;
+    rt_uint8_t *buffer; /**< Audio buffer information */
+    rt_uint16_t block_size; /**< Audio block_size information for replay function */
+    rt_uint16_t block_count; /**< Audio block_count information for replay function */
+    rt_uint32_t total_size; /**< Audio total_size which is equal to block_size multiplying
+                                block_count information for replay function */
+
 };
 
 struct rt_audio_device;
 struct rt_audio_caps;
 struct rt_audio_configure;
+
+/**
+ * @brief Aduio device operators
+ */
 struct rt_audio_ops
 {
-    rt_err_t (*getcaps)(struct rt_audio_device *audio, struct rt_audio_caps *caps);
-    rt_err_t (*configure)(struct rt_audio_device *audio, struct rt_audio_caps *caps);
-    rt_err_t (*init)(struct rt_audio_device *audio);
-    rt_err_t (*start)(struct rt_audio_device *audio, int stream);
-    rt_err_t (*stop)(struct rt_audio_device *audio, int stream);
-    rt_ssize_t (*transmit)(struct rt_audio_device *audio, const void *writeBuf, void *readBuf, rt_size_t size);
-    /* get page size of codec or private buffer's info */
-    void (*buffer_info)(struct rt_audio_device *audio, struct rt_audio_buf_info *info);
+    rt_err_t (*getcaps)(struct rt_audio_device *audio, struct rt_audio_caps *caps); /**< Get audio capabilities information */
+    rt_err_t (*configure)(struct rt_audio_device *audio, struct rt_audio_caps *caps); /**< Configure audio devices */
+    rt_err_t (*init)(struct rt_audio_device *audio); /**< Initialize audio device */
+    rt_err_t (*start)(struct rt_audio_device *audio, int stream); /**< Turn on the audio device */
+    rt_err_t (*stop)(struct rt_audio_device *audio, int stream); /**< Turn off the audio device */
+    rt_ssize_t (*transmit)(struct rt_audio_device *audio, const void *writeBuf, void *readBuf, rt_size_t size); /**< Transmit data between application and device */
+    void (*buffer_info)(struct rt_audio_device *audio, struct rt_audio_buf_info *info); /**< Get page size of codec or private buffer's info */
path: components/drivers/include/drivers/dev_audio.h
user: login: unicornx
body: 这里放在后面感觉一行太长了，代码里我们一般都有对一行限制长度的要求。

原来对结构体成员的 doxygen 注释没有考虑到 callback 的情况，普通结构体成员一般不会那么长。

我建议改良一下，我试了一下，可以将注释移到 callback 成员的前面去，你看看还行，例子如下, 可以写 `@brief` ，也可以不写, 需要注意的是，如果不写在行尾，则不要写成 `/**<` , 即不要 `<`：

```c
/**
 * @brief Aduio device operators
 */
struct rt_audio_ops
{
    /** @brief Get audio capabilities information */
    rt_err_t (*getcaps)(struct rt_audio_device *audio, struct rt_audio_caps *caps); 
    
    /** Configure audio devices */
    rt_err_t (*configure)(struct rt_audio_device *audio, struct rt_audio_caps *caps);

    // ......
};
```

更近一步，对于这种成员是回调函数的结构体，我发现可以写成下面这样，从而可以对 callback 函数做更详细的说明，你看看要不要写成这样，只是写法比较复杂，内容比较多。主要是考虑到可能需要对 callback 函数的参数和返回值等进行更多的描述时会有用。

```c
/**
 * @brief Aduio device operators
 */
struct rt_audio_ops
{
    /** @brief Get audio capabilities information
     *  @param audio the audio device
     *  @param caps the audio capabilities information
     *  @return the operation status, RT_EOK on successful
     */
    rt_err_t (*getcaps)(struct rt_audio_device *audio, struct rt_audio_caps *caps); 
    //......
};
```

你看看怎么写。定下来我也去更新一下 https://rt-thread.github.io/rt-thread/page_howto_struct.html


created_at: 2025-03-05T01:17:35Z
author_association: CONTRIBUTOR
diff_hunk: @@ -181,25 +183,30 @@ enum
  */
 struct rt_audio_buf_info
 {
-    rt_uint8_t *buffer;
-    rt_uint16_t block_size;
-    rt_uint16_t block_count;
-    rt_uint32_t total_size;
+    rt_uint8_t *buffer; /**< Audio buffer information */
+    rt_uint16_t block_size; /**< Audio block_size information for replay function */
+    rt_uint16_t block_count; /**< Audio block_count information for replay function */
+    rt_uint32_t total_size; /**< Audio total_size which is equal to block_size multiplying
+                                block_count information for replay function */
+
path: components/drivers/include/drivers/dev_audio.h
user: login: unicornx
body: 行尾的注释对齐一下会更好看。
created_at: 2025-03-05T01:18:15Z
author_association: CONTRIBUTOR
diff_hunk: @@ -181,24 +183,35 @@ enum
  */
 struct rt_audio_buf_info
 {
-    rt_uint8_t *buffer;
-    rt_uint16_t block_size;
-    rt_uint16_t block_count;
-    rt_uint32_t total_size;
+    rt_uint8_t *buffer; /**< Audio buffer information                                       */
+    rt_uint16_t block_size; /**< Audio block_size information for replay function           */
+    rt_uint16_t block_count; /**< Audio block_count information for replay function         */
+    rt_uint32_t total_size; /**< Audio total_size which is equal to block_size multiplying
path: components/drivers/include/drivers/dev_audio.h
user: login: unicornx
body: 这些行尾注释请对齐。就像前面对宏的那样。
created_at: 2025-03-06T00:37:02Z
author_association: CONTRIBUTOR
diff_hunk: @@ -211,43 +224,45 @@ struct rt_audio_ops
  */
 struct rt_audio_configure
 {
-    rt_uint32_t samplerate;
-    rt_uint16_t channels;
-    rt_uint16_t samplebits;
+    rt_uint32_t samplerate; /**< Audio samplerate information */
+    rt_uint16_t channels; /**< Audio channels information */
+    rt_uint16_t samplebits; /**< Audio samplebits information */
path: components/drivers/include/drivers/dev_audio.h
user: login: unicornx
body: 这些行尾注释请对齐。就像前面对宏的那样。
created_at: 2025-03-06T00:37:11Z
author_association: CONTRIBUTOR
diff_hunk: @@ -211,43 +224,45 @@ struct rt_audio_ops
  */
 struct rt_audio_configure
 {
-    rt_uint32_t samplerate;
-    rt_uint16_t channels;
-    rt_uint16_t samplebits;
+    rt_uint32_t samplerate; /**< Audio samplerate information */
+    rt_uint16_t channels; /**< Audio channels information */
+    rt_uint16_t samplebits; /**< Audio samplebits information */
 };
 
 /**
  * @brief Audio capabilities
  */
 struct rt_audio_caps
 {
-    int main_type;
-    int sub_type;
+    int main_type; /**< Audio main type, one value of @ref audio_type               */
+    int sub_type; /**< Audio sub type, one value of @ref audio_dsp @ref audio_mixer */
path: components/drivers/include/drivers/dev_audio.h
user: login: unicornx
body: 这些行尾注释请对齐。就像前面对宏的那样。
created_at: 2025-03-06T00:37:17Z
author_association: CONTRIBUTOR
diff_hunk: @@ -211,43 +224,45 @@ struct rt_audio_ops
  */
 struct rt_audio_configure
 {
-    rt_uint32_t samplerate;
-    rt_uint16_t channels;
-    rt_uint16_t samplebits;
+    rt_uint32_t samplerate; /**< Audio samplerate information */
+    rt_uint16_t channels; /**< Audio channels information */
+    rt_uint16_t samplebits; /**< Audio samplebits information */
 };
 
 /**
  * @brief Audio capabilities
  */
 struct rt_audio_caps
 {
-    int main_type;
-    int sub_type;
+    int main_type; /**< Audio main type, one value of @ref audio_type               */
+    int sub_type; /**< Audio sub type, one value of @ref audio_dsp @ref audio_mixer */
 
     union
     {
-        rt_uint32_t mask;
-        int     value;
-        struct rt_audio_configure config;
-    } udata;
+        rt_uint32_t mask; /**< Capabilities mask                                    */
+        int     value; /**< Capabilities value                                      */
+        struct rt_audio_configure config; /**< Audio samplebits information         */
path: components/drivers/include/drivers/dev_audio.h
user: login: unicornx
body: 这些行尾注释请对齐。就像前面对宏的那样。
created_at: 2025-03-06T00:37:32Z
author_association: CONTRIBUTOR
diff_hunk: @@ -211,43 +224,45 @@ struct rt_audio_ops
  */
 struct rt_audio_configure
 {
-    rt_uint32_t samplerate;
-    rt_uint16_t channels;
-    rt_uint16_t samplebits;
+    rt_uint32_t samplerate; /**< Audio samplerate information */
+    rt_uint16_t channels; /**< Audio channels information */
+    rt_uint16_t samplebits; /**< Audio samplebits information */
 };
 
 /**
  * @brief Audio capabilities
  */
 struct rt_audio_caps
 {
-    int main_type;
-    int sub_type;
+    int main_type; /**< Audio main type, one value of @ref audio_type               */
+    int sub_type; /**< Audio sub type, one value of @ref audio_dsp @ref audio_mixer */
 
     union
     {
-        rt_uint32_t mask;
-        int     value;
-        struct rt_audio_configure config;
-    } udata;
+        rt_uint32_t mask; /**< Capabilities mask                                    */
+        int     value; /**< Capabilities value                                      */
+        struct rt_audio_configure config; /**< Audio samplebits information         */
+    } udata; /**< User data */
 };
 
 /**
  * @brief Audio replay
  */
 struct rt_audio_replay
 {
-    struct rt_mempool *mp;
-    struct rt_data_queue queue;
-    struct rt_mutex lock;
-    struct rt_completion cmp;
-    struct rt_audio_buf_info buf_info;
-    rt_uint8_t *write_data;
-    rt_uint16_t write_index;
-    rt_uint16_t read_index;
-    rt_uint32_t pos;
-    rt_uint8_t event;
-    rt_bool_t activated;
+    struct rt_mempool *mp; /**< Memory pool for audio replay                                    */
+    struct rt_data_queue queue; /**< Replay data queue                                          */
+    struct rt_mutex lock; /**< Replay mutex lock                                                */
+    struct rt_completion cmp; /**< Replay completion, it will be                                */
+    struct rt_audio_buf_info buf_info; /**< Replay buffer information                           */
+    rt_uint8_t *write_data; /**< Pointer to the data to be written into data queue              */
+    rt_uint16_t write_index; /**< Index of pointer write_data.It records how much data
+                                 has been written in currently being played block               */
+    rt_uint16_t read_index; /**< Index of replaying data for audio device, it indicates index
+                                 of replay in the blocks which is currently being played        */
+    rt_uint32_t pos; /**< Global position of audio replay                                       */
+    rt_uint8_t event; /**< Event flag                                                           */
+    rt_bool_t activated; /**< Activaty flag                                                     */
 };
path: components/drivers/include/drivers/dev_audio.h
user: login: unicornx
body: 这些行尾注释请对齐。就像前面对宏的那样。尾巴其实不用对齐，前面对齐就好：
可以用 TAB 键，然后保存时 TAB 转空格即可。貌似 RTT 这里缩进不用 TAB 的，和 linux 不一样。

```c
struct rt_audio_replay
{
    struct rt_mempool *mp;      /**< Memory pool for audio replay */
    struct rt_data_queue queue; /**< Replay data queue */
    struct rt_mutex lock;       /**< Replay mutex lock */ 
    ....
};
```
created_at: 2025-03-06T00:40:09Z
author_association: CONTRIBUTOR
diff_hunk: @@ -264,10 +279,10 @@ struct rt_audio_record
  */
 struct rt_audio_device
 {
-    struct rt_device           parent;
-    struct rt_audio_ops        *ops;
-    struct rt_audio_replay     *replay;
-    struct rt_audio_record     *record;
+    struct rt_device           parent; /**< Audio device parents */
+    struct rt_audio_ops        *ops; /**< Audio device operator */
+    struct rt_audio_replay     *replay; /**< Pointer to audio replay structure */
+    struct rt_audio_record     *record; /**< Pointer to audio record structure */
path: components/drivers/include/drivers/dev_audio.h
user: login: unicornx
body: 这些行尾注释请对齐。就像前面对宏的那样。
created_at: 2025-03-06T00:40:30Z
author_association: CONTRIBUTOR
diff_hunk: @@ -211,43 +224,45 @@ struct rt_audio_ops
  */
 struct rt_audio_configure
 {
-    rt_uint32_t samplerate;
-    rt_uint16_t channels;
-    rt_uint16_t samplebits;
+    rt_uint32_t samplerate; /**< Audio samplerate information */
+    rt_uint16_t channels; /**< Audio channels information */
+    rt_uint16_t samplebits; /**< Audio samplebits information */
 };
 
 /**
  * @brief Audio capabilities
  */
 struct rt_audio_caps
 {
-    int main_type;
-    int sub_type;
+    int main_type; /**< Audio main type, one value of @ref audio_type               */
+    int sub_type; /**< Audio sub type, one value of @ref audio_dsp @ref audio_mixer */
 
     union
     {
-        rt_uint32_t mask;
-        int     value;
-        struct rt_audio_configure config;
-    } udata;
+        rt_uint32_t mask; /**< Capabilities mask                                    */
+        int     value; /**< Capabilities value                                      */
+        struct rt_audio_configure config; /**< Audio samplebits information         */
+    } udata; /**< User data */
 };
 
 /**
  * @brief Audio replay
  */
 struct rt_audio_replay
 {
-    struct rt_mempool *mp;
-    struct rt_data_queue queue;
-    struct rt_mutex lock;
-    struct rt_completion cmp;
-    struct rt_audio_buf_info buf_info;
-    rt_uint8_t *write_data;
-    rt_uint16_t write_index;
-    rt_uint16_t read_index;
-    rt_uint32_t pos;
-    rt_uint8_t event;
-    rt_bool_t activated;
+    struct rt_mempool *mp; /**< Memory pool for audio replay                                    */
+    struct rt_data_queue queue; /**< Replay data queue                                          */
+    struct rt_mutex lock; /**< Replay mutex lock                                                */
+    struct rt_completion cmp; /**< Replay completion, it will be                                */
+    struct rt_audio_buf_info buf_info; /**< Replay buffer information                           */
+    rt_uint8_t *write_data; /**< Pointer to the data to be written into data queue              */
+    rt_uint16_t write_index; /**< Index of pointer write_data.It records how much data
+                                 has been written in currently being played block               */
+    rt_uint16_t read_index; /**< Index of replaying data for audio device, it indicates index
+                                 of replay in the blocks which is currently being played        */
+    rt_uint32_t pos; /**< Global position of audio replay                                       */
+    rt_uint8_t event; /**< Event flag                                                           */
+    rt_bool_t activated; /**< Activaty flag                                                     */
 };
path: components/drivers/include/drivers/dev_audio.h
user: login: 1078249029
body: > 这些行尾注释请对齐。就像前面对宏的那样。尾巴其实不用对齐，前面对齐就好： 可以用 TAB 键，然后保存时 TAB 转空格即可。貌似 RTT 这里缩进不用 TAB 的，和 linux 不一样。
> 
> ```c
> struct rt_audio_replay
> {
>     struct rt_mempool *mp;      /**< Memory pool for audio replay */
>     struct rt_data_queue queue; /**< Replay data queue */
>     struct rt_mutex lock;       /**< Replay mutex lock */ 
>     ....
> };
> ```

啊，是我理解错了。这种结构体成员长短不一的情况在 https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/include/struct.h 并没有说明，还是补充了吧？
created_at: 2025-03-06T01:24:58Z
author_association: CONTRIBUTOR
diff_hunk: @@ -211,43 +224,45 @@ struct rt_audio_ops
  */
 struct rt_audio_configure
 {
-    rt_uint32_t samplerate;
-    rt_uint16_t channels;
-    rt_uint16_t samplebits;
+    rt_uint32_t samplerate; /**< Audio samplerate information */
+    rt_uint16_t channels; /**< Audio channels information */
+    rt_uint16_t samplebits; /**< Audio samplebits information */
 };
 
 /**
  * @brief Audio capabilities
  */
 struct rt_audio_caps
 {
-    int main_type;
-    int sub_type;
+    int main_type; /**< Audio main type, one value of @ref audio_type               */
+    int sub_type; /**< Audio sub type, one value of @ref audio_dsp @ref audio_mixer */
 
     union
     {
-        rt_uint32_t mask;
-        int     value;
-        struct rt_audio_configure config;
-    } udata;
+        rt_uint32_t mask; /**< Capabilities mask                                    */
+        int     value; /**< Capabilities value                                      */
+        struct rt_audio_configure config; /**< Audio samplebits information         */
+    } udata; /**< User data */
 };
 
 /**
  * @brief Audio replay
  */
 struct rt_audio_replay
 {
-    struct rt_mempool *mp;
-    struct rt_data_queue queue;
-    struct rt_mutex lock;
-    struct rt_completion cmp;
-    struct rt_audio_buf_info buf_info;
-    rt_uint8_t *write_data;
-    rt_uint16_t write_index;
-    rt_uint16_t read_index;
-    rt_uint32_t pos;
-    rt_uint8_t event;
-    rt_bool_t activated;
+    struct rt_mempool *mp; /**< Memory pool for audio replay                                    */
+    struct rt_data_queue queue; /**< Replay data queue                                          */
+    struct rt_mutex lock; /**< Replay mutex lock                                                */
+    struct rt_completion cmp; /**< Replay completion, it will be                                */
+    struct rt_audio_buf_info buf_info; /**< Replay buffer information                           */
+    rt_uint8_t *write_data; /**< Pointer to the data to be written into data queue              */
+    rt_uint16_t write_index; /**< Index of pointer write_data.It records how much data
+                                 has been written in currently being played block               */
+    rt_uint16_t read_index; /**< Index of replaying data for audio device, it indicates index
+                                 of replay in the blocks which is currently being played        */
+    rt_uint32_t pos; /**< Global position of audio replay                                       */
+    rt_uint8_t event; /**< Event flag                                                           */
+    rt_bool_t activated; /**< Activaty flag                                                     */
 };
path: components/drivers/include/drivers/dev_audio.h
user: login: unicornx
body: > 啊，是我理解错了。这种结构体成员长短不一的情况在 https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/include/struct.h 并没有说明，还是补充了吧？

ok， 我另外提个 pr 来补充说明一下。


created_at: 2025-03-06T01:27:09Z
author_association: CONTRIBUTOR

PR comments:
user: login: 1078249029
created_at: 2025-03-04T12:50:47Z
body: @unicornx 我这里好像不能添加reviewer，只能pin一下了
author_association: CONTRIBUTOR
user: login: unicornx
created_at: 2025-03-06T02:04:31Z
body: 我发现有个地方可以改进一下，代码会简洁一些，

以下面代码为例：

```c
/**
 * @defgroup audio_control AUDIO_CTL
 *
 * @brief Control audio device.
 */

/**
 * @addtogroup audio_control
 * @{
 */

/**
 * @brief Generate audio command code with @a a
 *
 * @param[in] a offset of command.
 *
 * @return audio device control command code.
 */
#define _AUDIO_CTL(a) (RT_DEVICE_CTRL_BASE(Sound) + a)

#define AUDIO_CTL_GETCAPS                   _AUDIO_CTL(1) /**< Get audio device capabilities */
#define AUDIO_CTL_CONFIGURE                 _AUDIO_CTL(2) /**< Get audio device configuration */
#define AUDIO_CTL_START                     _AUDIO_CTL(3) /**< Start audio device  */
#define AUDIO_CTL_STOP                      _AUDIO_CTL(4) /**< Stop audio device */
#define AUDIO_CTL_GETBUFFERINFO             _AUDIO_CTL(5) /**< Get audio device buffer information */

/** @} */ /* End of audio_control */
```

这里 defgroup 了一个 audio_control 然后通过 addtogroup 将一些宏组织到一起。但其实可以省掉 addtogroup ，把 ”@{“ 直接写到 defgroup 里，这样代码会更好看。建议改进一下。
例子如下：

```c
/**
 * @defgroup audio_control AUDIO_CTL
 *
 * @brief Control audio device.
 * 
 * @{
 */

/**
 * @brief Generate audio command code with @a a
 *
 * @param[in] a offset of command.
 *
 * @return audio device control command code.
 */
#define _AUDIO_CTL(a) (RT_DEVICE_CTRL_BASE(Sound) + a)

#define AUDIO_CTL_GETCAPS                   _AUDIO_CTL(1) /**< Get audio device capabilities */
#define AUDIO_CTL_CONFIGURE                 _AUDIO_CTL(2) /**< Get audio device configuration */
#define AUDIO_CTL_START                     _AUDIO_CTL(3) /**< Start audio device  */
#define AUDIO_CTL_STOP                      _AUDIO_CTL(4) /**< Stop audio device */
#define AUDIO_CTL_GETBUFFERINFO             _AUDIO_CTL(5) /**< Get audio device buffer information */

/** @} */ /* End of audio_control */
```

author_association: CONTRIBUTOR
user: login: unicornx
created_at: 2025-03-06T03:22:14Z
body: @Rbb666 我已经 approve 了，你看看没问题请 merge，thanks
author_association: CONTRIBUTOR