[doxygen][audio] Fix doxygen comments for audio component #10073
+69
−74
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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,21 +21,15 @@ | |
| * @ingroup group_Drivers RT-Thread Drivers | ||
| * | ||
| * @brief Audio driver API. | ||
| * | ||
| * @{ | ||
| */ | ||
|
|
||
| /** | ||
| * @defgroup audio_control AUDIO_CTL | ||
| * | ||
| * @brief Control audio device. | ||
| * | ||
| * @{ | ||
| */ | ||
|
|
||
|
|
@@ -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 */ | ||
|
|
||
| /** | ||
| * @defgroup audio_type AUDIO_TYPE | ||
| * | ||
| * @brief Audio Device Types | ||
| * | ||
| * @{ | ||
| */ | ||
| #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. | ||
| * | ||
| * @{ | ||
| */ | ||
| #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 */ | ||
|
|
||
| /** | ||
| * @defgroup audio_bit_rates AUDIO_BIT_RATES | ||
| * | ||
| * @brief Supported bit rates for the audio device. | ||
| * | ||
| * @{ | ||
| */ | ||
| #define AUDIO_BIT_RATE_22K 0x01 /**< Set audio device bit rates to 22K */ | ||
|
|
@@ -114,48 +99,44 @@ | |
| #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 */ | ||
|
|
||
|
|
||
| /** | ||
| * @defgroup audio_dsp 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 */ | ||
|
|
||
| /** | ||
| * @defgroup audio_mixer 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_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) | ||
|
|
@@ -181,24 +162,35 @@ enum | |
| */ | ||
| struct rt_audio_buf_info | ||
| { | ||
| 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 */ | ||
| void (*buffer_info)(struct rt_audio_device *audio, struct rt_audio_buf_info *info); | ||
| }; | ||
|
|
||
|
|
@@ -211,43 +203,45 @@ struct rt_audio_ops | |
| */ | ||
| struct rt_audio_configure | ||
| { | ||
| 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; /**< 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; /**< 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; /**< 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 */ | ||
| }; | ||
|
There was a problem hiding this comment. 这些行尾注释请对齐。就像前面对宏的那样。尾巴其实不用对齐，前面对齐就好： 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 */
....
};There was a problem hiding this comment.
啊，是我理解错了。这种结构体成员长短不一的情况在 https://github.com/RT-Thread/rt-thread/blob/master/documentation/0.doxygen/example/include/struct.h 并没有说明，还是补充了吧？ There was a problem hiding this comment.
ok， 我另外提个 pr 来补充说明一下。 |
||
|
|
||
| /** | ||
|
|
@@ -264,10 +258,10 @@ struct rt_audio_record | |
| */ | ||
| struct rt_audio_device | ||
| { | ||
| 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. 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 */ | ||
|
|
||
| /** @} group_Audio */ | ||
|
|
||
|
|
||
File renamed without changes.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
文字和 ”*/“ 之间要加空格，譬如下面 ”audio_control“ 后面缺个空格：
这样的地方有好几处，请搜索并改正。