[doxygen][audio] Fix doxygen comments for audio component

Added comments for data structure and rt_audio_ops in dev_audio.h.
Enriched comments for macro group. Moved and renamed folder audio.

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

Author: 1078249029

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
  */
 
 /** @{ */

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>

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__

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__
@@ -54,7 +54,7 @@
 #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
@@ -70,7 +70,7 @@
 #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
@@ -94,7 +94,7 @@
 #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
@@ -114,13 +114,14 @@
 #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
+ * @brief Support Dsp(input/output) Units controls. The macro group from application level, can
+ *        set audio mixer parameters including samplerate, channels etc.
  */
 
 /**
@@ -131,12 +132,13 @@
 #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
+ * @brief Supported Mixer Units controls. The macro group from driver level, can set audio mixer
+ *        parameters including volume, frequence db, microphone etc.
  */
 
 /**
@@ -147,15 +149,15 @@
 #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 */
 #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*/
+/** @} */ /* End of audio_mixer */
 
 #define AUDIO_VOLUME_MAX                    (100)
 #define AUDIO_VOLUME_MIN                    (0)
@@ -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
+                                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,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                                                     */
 };
 
 /**
@@ -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 */
 };
 
 rt_err_t    rt_audio_register(struct rt_audio_device *audio, const char *name, rt_uint32_t flag, void *data);
@@ -277,7 +292,8 @@ 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
+ * @brief Device Control Commands. The macro group from hardware level, can set codec
+ *        parametes including volume, EQ and 3D etc.
  */
 
 /**
@@ -292,7 +308,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 */