[RFC][doxygen]Doxygen comment standard processing (#10058)

Signed-off-by: 1078249029 <[email protected]>

4 files changed, 458 insertions, 84 deletions

diff --git a/components/drivers/audio/dev_audio.c b/components/drivers/audio/dev_audio.c
index 22ee81e51f..fd5bc47206 100644
--- a/components/drivers/audio/dev_audio.c
+++ b/components/drivers/audio/dev_audio.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006-2023, RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -22,6 +22,12 @@
 #define MIN(a, b)         ((a) < (b) ? (a) : (b))
 #endif
 
+/**
+ * @addtogroup group_AudioPipe
+ */
+
+/** @{ */
+
 enum
 {
     REPLAY_EVT_NONE  = 0x00,
@@ -29,6 +35,20 @@ enum
     REPLAY_EVT_STOP  = 0x02,
 };
 
+/**
+ * @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
+ *
+ * @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
+ */
 static rt_err_t _audio_send_replay_frame(struct rt_audio_device *audio)
 {
     rt_err_t result = RT_EOK;
@@ -108,6 +128,13 @@ static rt_err_t _audio_send_replay_frame(struct rt_audio_device *audio)
     return result;
 }
 
+/**
+ * @brief Write replay frame into audio device replay queue
+ *
+ * @param[in] audio pointer to audio device
+ *
+ * @return error code, RT_EOK is successful otherwise means failure
+ */
 static rt_err_t _audio_flush_replay_frame(struct rt_audio_device *audio)
 {
     rt_err_t result = RT_EOK;
@@ -125,6 +152,13 @@ static rt_err_t _audio_flush_replay_frame(struct rt_audio_device *audio)
     return result;
 }
 
+/**
+ * @brief Replay audio
+ *
+ * @param[in] audio pointer to audio device
+ *
+ * @return error code, RT_EOK is successful otherwise means failure
+ */
 static rt_err_t _aduio_replay_start(struct rt_audio_device *audio)
 {
     rt_err_t result = RT_EOK;
@@ -142,6 +176,16 @@ static rt_err_t _aduio_replay_start(struct rt_audio_device *audio)
     return result;
 }
 
+/**
+ * @brief Stop replaying audio
+ *
+ * When audio->replay->queue is empty and the audio->replay->event was set REPLAY_EVT_STOP,
+ * _audio_send_replay_frame will send completion to stop replaying audio.
+ *
+ * @param[in] audio pointer to audio device
+ *
+ * @return error code, RT_EOK is successful otherwise means failure
+ */
 static rt_err_t _aduio_replay_stop(struct rt_audio_device *audio)
 {
     rt_err_t result = RT_EOK;
@@ -170,6 +214,13 @@ static rt_err_t _aduio_replay_stop(struct rt_audio_device *audio)
     return result;
 }
 
+/**
+ * @brief Open audio pipe and start to record audio
+ *
+ * @param[in] audio pointer to audio device
+ *
+ * @return error code, RT_EOK is successful otherwise means failure
+ */
 static rt_err_t _audio_record_start(struct rt_audio_device *audio)
 {
     rt_err_t result = RT_EOK;
@@ -190,6 +241,13 @@ static rt_err_t _audio_record_start(struct rt_audio_device *audio)
     return result;
 }
 
+/**
+ * @brief stop recording audio and closeaudio pipe
+ *
+ * @param[in] audio pointer to audio device
+ *
+ * @return error code, RT_EOK is successful otherwise means failure
+ */
 static rt_err_t _audio_record_stop(struct rt_audio_device *audio)
 {
     rt_err_t result = RT_EOK;
@@ -210,6 +268,20 @@ static rt_err_t _audio_record_stop(struct rt_audio_device *audio)
     return result;
 }
 
+/**
+ * @brief Init audio pipe
+ *
+ * In kernel, this function will set replay or record function depending on device
+ * flag. For replaying, it will malloc for managing audio replay struct meanwhile
+ * creating mempool and dataqueue.For recording, it will creat audio pipe and
+ * it's ringbuffer.
+ * In driver, this function will only execute hardware driver initialization code
+ * and get hardware buffer infomation.
+ *
+ * @param[in] dev pointer to audio device
+ *
+ * @return error code, RT_EOK is successful otherwise means failure
+ */
 static rt_err_t _audio_dev_init(struct rt_device *dev)
 {
     rt_err_t result = RT_EOK;
@@ -288,6 +360,15 @@ static rt_err_t _audio_dev_init(struct rt_device *dev)
     return result;
 }
 
+/**
+ * @brief Start record audio
+ *
+ * @param[in] dev pointer to audio device
+ *
+ * @param[in] oflag device flag
+ *
+ * @return error code, RT_EOK is successful otherwise means failure
+ */
 static rt_err_t _audio_dev_open(struct rt_device *dev, rt_uint16_t oflag)
 {
     struct rt_audio_device *audio;
@@ -334,6 +415,13 @@ static rt_err_t _audio_dev_open(struct rt_device *dev, rt_uint16_t oflag)
     return RT_EOK;
 }
 
+/**
+ * @brief Stop record, replay or both.
+ *
+ * @param[in] dev pointer to audio device
+ *
+ * @return useless param
+ */
 static rt_err_t _audio_dev_close(struct rt_device *dev)
 {
     struct rt_audio_device *audio;
@@ -357,6 +445,21 @@ static rt_err_t _audio_dev_close(struct rt_device *dev)
     return RT_EOK;
 }
 
+/**
+ * @brief Read audio device
+ *
+ * @param[in] dev pointer to device
+ *
+ * @param[in] pos position when reading
+ *
+ * @param[out] buffer a data buffer to save the read data
+ *
+ * @param[in] size buffer size
+ *
+ * @return the actually read size on successfully, otherwise 0 will be returned.
+ *
+ * @note
+ */
 static rt_ssize_t _audio_dev_read(struct rt_device *dev, rt_off_t pos, void *buffer, rt_size_t size)
 {
     struct rt_audio_device *audio;
@@ -369,6 +472,21 @@ static rt_ssize_t _audio_dev_read(struct rt_device *dev, rt_off_t pos, void *buf
     return rt_device_read(RT_DEVICE(&audio->record->pipe), pos, buffer, size);
 }
 
+/**
+ * @brief Write data into replay data queue and replay it
+ *
+ * @param[in] dev pointer to device
+ *
+ * @param[in] pos useless param
+ *
+ * @param[in] buffer a data buffer to be written into data queue
+ *
+ * @param[in] size buffer size
+ *
+ * @return the actually read size on successfully, otherwise 0 will be returned.
+ *
+ * @note This function will take mutex.
+ */
 static rt_ssize_t _audio_dev_write(struct rt_device *dev, rt_off_t pos, const void *buffer, rt_size_t size)
 {
 
@@ -424,6 +542,17 @@ static rt_ssize_t _audio_dev_write(struct rt_device *dev, rt_off_t pos, const vo
     return index;
 }
 
+/**
+ * @brief Control audio device
+ *
+ * @param[in] dev pointer to device
+ *
+ * @param[in] cmd audio cmd, it can be one of value in @ref audio_control
+ *
+ * @param[in] args command argument
+ *
+ * @return error code, RT_EOK is successful otherwise means failure
+ */
 static rt_err_t _audio_dev_control(struct rt_device *dev, int cmd, void *args)
 {
     rt_err_t result = RT_EOK;
@@ -513,6 +642,19 @@ const static struct rt_device_ops audio_ops =
 };
 #endif
 
+/**
+ * @brief Register and initialize audio device
+ *
+ * @param[in] audio pointer to audio deive
+ *
+ * @param[in] name device name
+ *
+ * @param[in] flag device flags
+ *
+ * @param[in] data user data
+ *
+ * @return error code, RT_EOK is successful otherwise means failure
+ */
 rt_err_t rt_audio_register(struct rt_audio_device *audio, const char *name, rt_uint32_t flag, void *data)
 {
     rt_err_t result = RT_EOK;
@@ -547,6 +689,13 @@ rt_err_t rt_audio_register(struct rt_audio_device *audio, const char *name, rt_u
     return result;
 }
 
+/**
+ * @brief Set audio sample rate
+ *
+ * @param[in] bitValue audio sample rate, it can be one of value in @ref audio_samp_rates
+ *
+ * @return speed has been set
+ */
 int rt_audio_samplerate_to_speed(rt_uint32_t bitValue)
 {
     int speed = 0;
@@ -595,12 +744,32 @@ int rt_audio_samplerate_to_speed(rt_uint32_t bitValue)
     return speed;
 }
 
+/**
+ * @brief Send a replay frame to the audio hardware device
+ *
+ * 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)
 {
     /* try to send next frame */
     _audio_send_replay_frame(audio);
 }
 
+/**
+ * @brief Receive recording from audio device
+ *
+ * @param[in] audio pointer to audio device
+ *
+ * @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)
 {
     /* save data to record pipe */
@@ -610,3 +779,5 @@ void rt_audio_rx_done(struct rt_audio_device *audio, rt_uint8_t *pbuf, rt_size_t
     if (audio->parent.rx_indicate != RT_NULL)
         audio->parent.rx_indicate(&audio->parent, len);
 }
+
+/** @} group_Audio */
\ No newline at end of file
diff --git a/components/drivers/audio/dev_audio_pipe.c b/components/drivers/audio/dev_audio_pipe.c
index 24c0f26758..80f671b8c2 100644
--- a/components/drivers/audio/dev_audio_pipe.c
+++ b/components/drivers/audio/dev_audio_pipe.c
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006-2023, RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -30,6 +30,22 @@ static void _rt_audio_pipe_resume_writer(struct rt_audio_pipe *pipe)
     }
 }
 
+/**
+ * @brief Read audio pipe
+ *
+ * @param[in] dev pointer to audio device will be read
+ *
+ * @param[in] pos useless param
+ *
+ * @param[in] buffer pointer to ringbuffer of audio pipe to be read
+ *
+ * @param[in] size number of bytes will be read
+ *
+ * @return number of read bytes
+ *
+ * @note This function will execute time-consuming or affecting the
+ *       system operations like memcpy and disable interrupt.
+ */
 static rt_ssize_t rt_audio_pipe_read(rt_device_t dev,
                               rt_off_t    pos,
                               void       *buffer,
@@ -88,6 +104,11 @@ static rt_ssize_t rt_audio_pipe_read(rt_device_t dev,
     return read_nbytes;
 }
 
+/**
+ * @brief Resume audio pipe reader thread
+ *
+ * @param[in] pipe pointer to suspended audio pipe thread
+ */
 static void _rt_audio_pipe_resume_reader(struct rt_audio_pipe *pipe)
 {
     if (pipe->parent.rx_indicate)
@@ -110,6 +131,21 @@ static void _rt_audio_pipe_resume_reader(struct rt_audio_pipe *pipe)
     }
 }
 
+/**
+ * @brief Write data into audio pipe
+ *
+ * @param[in] dev pointer to audio pipe that has been configured
+ *
+ * @param[in] pos useless param
+ *
+ * @param[in] buffer pointer to buffer of ringbuffer
+ *
+ * @param[in] size size of data will be written
+ *
+ * @return number of written bytes
+ *
+ * @note The function will disable interrupt and may suspend current thread
+ */
 static rt_ssize_t rt_audio_pipe_write(rt_device_t dev,
                                rt_off_t    pos,
                                const void *buffer,
@@ -174,6 +210,17 @@ static rt_ssize_t rt_audio_pipe_write(rt_device_t dev,
     return write_nbytes;
 }
 
+/**
+ * @brief Control audio pipe
+ *
+ * @param[in] dev pointer to pipe
+ *
+ * @param[in] cmd control command
+ *
+ * @param[in] args control argument
+ *
+ * @return error code, RT_EOK is successful otherwise means failure
+ */
 static rt_err_t rt_audio_pipe_control(rt_device_t dev, int cmd, void *args)
 {
     struct rt_audio_pipe *pipe;
@@ -198,13 +245,19 @@ const static struct rt_device_ops audio_pipe_ops =
 #endif
 
 /**
+ * @brief Init audio pipe
+ *
  * This function will initialize a pipe device and put it under control of
  * resource management.
  *
  * @param pipe the pipe device
+ *
  * @param name the name of pipe device
+ *
  * @param flag the attribute of the pipe device
+ *
  * @param buf  the buffer of pipe device
+ *
  * @param size the size of pipe device buffer
  *
  * @return the operation status, RT_EOK on successful
@@ -244,7 +297,7 @@ rt_err_t rt_audio_pipe_init(struct rt_audio_pipe *pipe,
 }
 
 /**
- * This function will detach a pipe device from resource management
+ * @brief This function will detach a pipe device from resource management
  *
  * @param pipe the pipe device
  *
@@ -255,6 +308,19 @@ rt_err_t rt_audio_pipe_detach(struct rt_audio_pipe *pipe)
     return rt_device_unregister(&pipe->parent);
 }
 
+/**
+ * @brief Creat audio pipe
+ *
+ * @param[in] name pipe name
+ *
+ * @param[in] flag pipe flags, it can be one of enum rt_audio_pipe_flag items
+ *
+ * @param[in] size ringbuffer size
+ *
+ * @return error code, RT_EOK on initialization successfully
+ *
+ * @note depend on RT_USING_HEAP
+ */
 #ifdef RT_USING_HEAP
 rt_err_t rt_audio_pipe_create(const char *name, rt_int32_t flag, rt_size_t size)
 {
@@ -278,6 +344,13 @@ rt_err_t rt_audio_pipe_create(const char *name, rt_int32_t flag, rt_size_t size)
     return rt_audio_pipe_init(pipe, name, flag, rb_memptr, size);
 }
 
+/**
+ * @brief Detachaudio pipe and free its ringbuffer
+ *
+ * @param[in] pipe pointer to the pipe will be destory
+ *
+ * @note depend on RT_USING_HEAP
+ */
 void rt_audio_pipe_destroy(struct rt_audio_pipe *pipe)
 {
     if (pipe == RT_NULL)
@@ -293,4 +366,4 @@ void rt_audio_pipe_destroy(struct rt_audio_pipe *pipe)
     return;
 }
 
-#endif /* RT_USING_HEAP */
+#endif /* RT_USING_HEAP */
\ No newline at end of file
diff --git a/components/drivers/audio/dev_audio_pipe.h b/components/drivers/audio/dev_audio_pipe.h
index f22fd14a1f..5050c7baa8 100644
--- a/components/drivers/audio/dev_audio_pipe.h
+++ b/components/drivers/audio/dev_audio_pipe.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006-2023, RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -20,7 +20,9 @@
 #define PIPE_BUFSZ    RT_PIPE_BUFSZ
 #endif
 
-/* portal device */
+/**
+ * @brief Portal device
+ */
 struct rt_audio_portal_device
 {
     struct rt_device parent;
@@ -28,38 +30,43 @@ struct rt_audio_portal_device
     struct rt_device *read_dev;
 };
 
+/**
+ * @brief Aduio pipe flags
+ */
 enum rt_audio_pipe_flag
 {
-    /* both read and write won't block */
-    RT_PIPE_FLAG_NONBLOCK_RDWR = 0x00,
-    /* read would block */
-    RT_PIPE_FLAG_BLOCK_RD = 0x01,
-    /* write would block */
-    RT_PIPE_FLAG_BLOCK_WR = 0x02,
-    /* write to this pipe will discard some data when the pipe is full.
-     * When this flag is set, RT_PIPE_FLAG_BLOCK_WR will be ignored since write
-     * operation will always be success. */
-    RT_PIPE_FLAG_FORCE_WR = 0x04,
+
+    RT_PIPE_FLAG_NONBLOCK_RDWR = 0x00, /**< both read and write won't block */
+    RT_PIPE_FLAG_BLOCK_RD = 0x01, /**< read would block */
+    RT_PIPE_FLAG_BLOCK_WR = 0x02, /**< write would block */
+    RT_PIPE_FLAG_FORCE_WR = 0x04, /**< write to this pipe will discard some data when the pipe is full.
+                                    * When this flag is set, RT_PIPE_FLAG_BLOCK_WR will be ignored since write
+                                    * operation will always be success. */
 };
 
+/**
+ * @brief Audio buffer info
+ *
+ * The preferred number and size of audio pipeline buffer for the audio device, it
+ * will be used in rt_audio_replay struct.
+ *
+ */
 struct rt_audio_pipe
 {
     struct rt_device parent;
 
-    /* ring buffer in pipe device */
-    struct rt_ringbuffer ringbuffer;
+    struct rt_ringbuffer ringbuffer; /**< ring buffer in pipe device */
 
     rt_int32_t flag;
 
-    /* suspended list */
-    rt_list_t suspended_read_list;
-    rt_list_t suspended_write_list;
+    rt_list_t suspended_read_list; /**< suspended thread list for reading */
+    rt_list_t suspended_write_list; /**< suspended thread list for writing  */
 
     struct rt_audio_portal_device *write_portal;
     struct rt_audio_portal_device *read_portal;
 };
 
-#define PIPE_CTRL_GET_SPACE          0x14            /**< get the remaining size of a pipe device */
+#define PIPE_CTRL_GET_SPACE          0x14 /**< get the remaining size of a pipe device */
 
 rt_err_t rt_audio_pipe_init(struct rt_audio_pipe *pipe,
                       const char *name,
@@ -72,4 +79,4 @@ rt_err_t rt_audio_pipe_create(const char *name, rt_int32_t flag, rt_size_t size)
 void rt_audio_pipe_destroy(struct rt_audio_pipe *pipe);
 #endif /* RT_USING_HEAP */
 
-#endif /* __DEV_AUDIO_PIPE_H__ */
+#endif /* __DEV_AUDIO_PIPE_H__ */
\ No newline at end of file
diff --git a/components/drivers/include/drivers/dev_audio.h b/components/drivers/include/drivers/dev_audio.h
index ef92a935ab..9d9e1af632 100644
--- a/components/drivers/include/drivers/dev_audio.h
+++ b/components/drivers/include/drivers/dev_audio.h
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2006-2023, RT-Thread Development Team
+ * Copyright (c) 2006-2025 RT-Thread Development Team
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -15,70 +15,156 @@
 
 #include "dev_audio_pipe.h"
 
-/* AUDIO command */
+/**
+ * @defgroup group_Audio Audio
+ *
+ * @ingroup group_Drivers RT-Thread Drivers
+ *
+ * @brief Audio driver API.
+ */
+
+/**
+ * @addtogroup group_Audio
+ * @{
+ */
+
+/**
+ * @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)
-#define AUDIO_CTL_CONFIGURE                 _AUDIO_CTL(2)
-#define AUDIO_CTL_START                     _AUDIO_CTL(3)
-#define AUDIO_CTL_STOP                      _AUDIO_CTL(4)
-#define AUDIO_CTL_GETBUFFERINFO             _AUDIO_CTL(5)
+#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_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*/
+
+/**
+ * @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 */
+#define AUDIO_SAMP_RATE_11K                 0x0002 /**< Set audio device sample rate to 11K */
+#define AUDIO_SAMP_RATE_16K                 0x0004 /**< Set audio device sample rate to 16K */
+#define AUDIO_SAMP_RATE_22K                 0x0008 /**< Set audio device sample rate to 22K */
+#define AUDIO_SAMP_RATE_32K                 0x0010 /**< Set audio device sample rate to 32K */
+#define AUDIO_SAMP_RATE_44K                 0x0020 /**< Set audio device sample rate to 44K */
+#define AUDIO_SAMP_RATE_48K                 0x0040 /**< Set audio device sample rate to 48K */
+#define AUDIO_SAMP_RATE_96K                 0x0080 /**< Set audio device sample rate to 96K */
+#define AUDIO_SAMP_RATE_128K                0x0100 /**< Set audio device sample rate to 128K */
+#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*/
+
+/**
+ * @defgroup audio_bit_rates AUDIO_BIT_RATES
+ *
+ * @brief Supported bit rates for the audio device.
+ */
 
-/* Audio Device Types */
-#define AUDIO_TYPE_QUERY                    0x00
-#define AUDIO_TYPE_INPUT                    0x01
-#define AUDIO_TYPE_OUTPUT                   0x02
-#define AUDIO_TYPE_MIXER                    0x04
+/**
+ * @addtogroup audio_bit_rates
+ * @{
+ */
+#define AUDIO_BIT_RATE_22K                  0x01 /**< Set audio device bit rates to 22K */
+#define AUDIO_BIT_RATE_44K                  0x02 /**< Set audio device bit rates to 44K */
+#define AUDIO_BIT_RATE_48K                  0x04 /**< Set audio device bit rates to 48K */
+#define AUDIO_BIT_RATE_96K                  0x08 /**< Set audio device bit rates to 96K */
+#define AUDIO_BIT_RATE_128K                 0x10 /**< Set audio device bit rates to 128K */
+#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*/
 
-/* Supported Sampling Rates */
-#define AUDIO_SAMP_RATE_8K                  0x0001
-#define AUDIO_SAMP_RATE_11K                 0x0002
-#define AUDIO_SAMP_RATE_16K                 0x0004
-#define AUDIO_SAMP_RATE_22K                 0x0008
-#define AUDIO_SAMP_RATE_32K                 0x0010
-#define AUDIO_SAMP_RATE_44K                 0x0020
-#define AUDIO_SAMP_RATE_48K                 0x0040
-#define AUDIO_SAMP_RATE_96K                 0x0080
-#define AUDIO_SAMP_RATE_128K                0x0100
-#define AUDIO_SAMP_RATE_160K                0x0200
-#define AUDIO_SAMP_RATE_172K                0x0400
-#define AUDIO_SAMP_RATE_192K                0x0800
 
-/* Supported Bit Rates */
-#define AUDIO_BIT_RATE_22K                  0x01
-#define AUDIO_BIT_RATE_44K                  0x02
-#define AUDIO_BIT_RATE_48K                  0x04
-#define AUDIO_BIT_RATE_96K                  0x08
-#define AUDIO_BIT_RATE_128K                 0x10
-#define AUDIO_BIT_RATE_160K                 0x20
-#define AUDIO_BIT_RATE_172K                 0x40
-#define AUDIO_BIT_RATE_192K                 0x80
+/**
+ * @defgroup audio_dsp AUDIO_DSP
+ *
+ * @brief Support Dsp(input/output) Units controls
+ */
 
-/* Support Dsp(input/output) Units controls */
-#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 */
+/**
+ * @addtogroup audio_dsp
+ * @{
+ */
+#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*/
 
-/* Supported Mixer Units controls */
-#define AUDIO_MIXER_QUERY                   0x0000
-#define AUDIO_MIXER_MUTE                    0x0001
-#define AUDIO_MIXER_VOLUME                  0x0002
-#define AUDIO_MIXER_BASS                    0x0004
-#define AUDIO_MIXER_MID                     0x0008
-#define AUDIO_MIXER_TREBLE                  0x0010
-#define AUDIO_MIXER_EQUALIZER               0x0020
-#define AUDIO_MIXER_LINE                    0x0040
-#define AUDIO_MIXER_DIGITAL                 0x0080
-#define AUDIO_MIXER_MIC                     0x0100
-#define AUDIO_MIXER_VITURAL                 0x0200
-#define AUDIO_MIXER_EXTEND                  0x8000    /* extend mixer command */
+/**
+ * @defgroup audio_mixer AUDIO_MIXER
+ *
+ * @brief Supported Mixer Units controls
+ */
+
+/**
+ * @addtogroup audio_mixer
+ * @{
+ */
+#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_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 */
+#define AUDIO_MIXER_DIGITAL                 0x0080 /**< Set digital source */
+#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*/
 
 #define AUDIO_VOLUME_MAX                    (100)
 #define AUDIO_VOLUME_MIN                    (0)
 
 #define CFG_AUDIO_REPLAY_QUEUE_COUNT        4
 
+/**
+ * @brief Audio stream control command
+ */
 enum
 {
     AUDIO_STREAM_REPLAY = 0,
@@ -86,7 +172,13 @@ enum
     AUDIO_STREAM_LAST = AUDIO_STREAM_RECORD,
 };
 
-/* the preferred number and size of audio pipeline buffer for the audio device */
+/**
+ * @brief Audio buffer info
+ *
+ * The preferred number and size of audio pipeline buffer for the audio device, it
+ * will be used in rt_audio_replay struct.
+ *
+ */
 struct rt_audio_buf_info
 {
     rt_uint8_t *buffer;
@@ -110,6 +202,13 @@ struct rt_audio_ops
     void (*buffer_info)(struct rt_audio_device *audio, struct rt_audio_buf_info *info);
 };
 
+/**
+ * @brief Audio configuration
+ *
+ * The preferred number and size of audio pipeline buffer for the audio device, it
+ * will be used in rt_audio_caps struct.
+ *
+ */
 struct rt_audio_configure
 {
     rt_uint32_t samplerate;
@@ -117,6 +216,9 @@ struct rt_audio_configure
     rt_uint16_t samplebits;
 };
 
+/**
+ * @brief Audio capabilities
+ */
 struct rt_audio_caps
 {
     int main_type;
@@ -130,6 +232,9 @@ struct rt_audio_caps
     } udata;
 };
 
+/**
+ * @brief Audio replay
+ */
 struct rt_audio_replay
 {
     struct rt_mempool *mp;
@@ -145,12 +250,18 @@ struct rt_audio_replay
     rt_bool_t activated;
 };
 
+/**
+ * @brief Audio record, the audio device pipe container of ringbuffer
+ */
 struct rt_audio_record
 {
     struct rt_audio_pipe pipe;
     rt_bool_t activated;
 };
 
+/**
+ * @brief Audio device
+ */
 struct rt_audio_device
 {
     struct rt_device           parent;
@@ -163,14 +274,26 @@ rt_err_t    rt_audio_register(struct rt_audio_device *audio, const char *name, r
 void        rt_audio_tx_complete(struct rt_audio_device *audio);
 void        rt_audio_rx_done(struct rt_audio_device *audio, rt_uint8_t *pbuf, rt_size_t len);
 
-/* Device Control Commands */
-#define CODEC_CMD_RESET             0
-#define CODEC_CMD_SET_VOLUME        1
-#define CODEC_CMD_GET_VOLUME        2
-#define CODEC_CMD_SAMPLERATE        3
-#define CODEC_CMD_EQ                4
-#define CODEC_CMD_3D                5
+/**
+ * @defgroup audio_codec_cmd CODEC_CMD
+ *
+ * @brief Device Control Commands
+ */
+
+/**
+ * @addtogroup audio_codec_cmd
+ * @{
+ */
+#define CODEC_CMD_RESET             0 /**< Reset audio device by codec */
+#define CODEC_CMD_SET_VOLUME        1 /**< Set volume by codec */
+#define CODEC_CMD_GET_VOLUME        2 /**< Get volume by codec */
+#define CODEC_CMD_SAMPLERATE        3 /**< Set sample rate by codec */
+#define CODEC_CMD_EQ                4 /**< Set equalizer by codec */
+#define CODEC_CMD_3D                5 /**< Set 3D effect by codec */
 
 #define CODEC_VOLUME_MAX            (63)
+/** @} */ /* End of audio_codec_cmd*/
+
+/** @} group_Audio */
 
-#endif /* __DEV_AUDIO_H__ */
+#endif /* __DEV_AUDIO_H__ */
\ No newline at end of file