[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 <1078249029@qq.com>

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