docs: fix i2s section formatting

components/driver/i2s/include/driver/i2s_common.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -37,16 +37,16 @@ extern "C" {
  *       The variables used in the function should be in the SRAM as well.
  */
 typedef struct {
-    i2s_isr_callback_t on_recv;             /**< Callback of data received event, only for rx channel
+    i2s_isr_callback_t on_recv;             /**< Callback of data received event, only for RX channel
                                              *   The event data includes DMA buffer address and size that just finished receiving data
                                              */
-    i2s_isr_callback_t on_recv_q_ovf;       /**< Callback of receiving queue overflowed event, only for rx channel
+    i2s_isr_callback_t on_recv_q_ovf;       /**< Callback of receiving queue overflowed event, only for RX channel
                                              *   The event data includes buffer size that has been overwritten
                                              */
-    i2s_isr_callback_t on_sent;             /**< Callback of data sent event, only for tx channel
+    i2s_isr_callback_t on_sent;             /**< Callback of data sent event, only for TX channel
                                              *   The event data includes DMA buffer address and size that just finished sending data
                                              */
-    i2s_isr_callback_t on_send_q_ovf;       /**< Callback of sending queue overflowed event, only for tx channel
+    i2s_isr_callback_t on_send_q_ovf;       /**< Callback of sending queue overflowed event, only for TX channel
                                              *   The event data includes buffer size that has been overwritten
                                              */
 } i2s_event_callbacks_t;
@@ -61,9 +61,9 @@ typedef struct {
     /* DMA configurations */
     uint32_t            dma_desc_num;       /*!< I2S DMA buffer number, it is also the number of DMA descriptor */
     uint32_t            dma_frame_num;      /*!< I2S frame number in one DMA buffer. One frame means one-time sample data in all slots,
-                                             *   it should be the multiple of '3' when the data bit width is 24.
+                                             *   it should be the multiple of `3` when the data bit width is 24.
                                              */
-    bool                auto_clear;         /*!< Set to auto clear DMA TX buffer, i2s will always send zero automatically if no data to send */
+    bool                auto_clear;         /*!< Set to auto clear DMA TX buffer, I2S will always send zero automatically if no data to send */
     int                 intr_priority;      /*!< I2S interrupt priority, range [0, 7], if set to 0, the driver will try to allocate an interrupt with a relative low priority (1,2,3) */
 } i2s_chan_config_t;
 
@@ -82,16 +82,16 @@ typedef struct {
  * @brief Allocate new I2S channel(s)
  * @note  The new created I2S channel handle will be REGISTERED state after it is allocated successfully.
  * @note  When the port id in channel configuration is I2S_NUM_AUTO, driver will allocate I2S port automatically
- *        on one of the i2s controller, otherwise driver will try to allocate the new channel on the selected port.
+ *        on one of the I2S controller, otherwise driver will try to allocate the new channel on the selected port.
  * @note  If both tx_handle and rx_handle are not NULL, it means this I2S controller will work at full-duplex mode,
- *        the rx and tx channels will be allocated on a same I2S port in this case.
- *        Note that some configurations of tx/rx channel are shared on ESP32 and ESP32S2,
+ *        the RX and TX channels will be allocated on a same I2S port in this case.
+ *        Note that some configurations of TX/RX channel are shared on ESP32 and ESP32S2,
  *        so please make sure they are working at same condition and under same status(start/stop).
- *        Currently, full-duplex mode can't guarantee tx/rx channels write/read synchronously,
+ *        Currently, full-duplex mode can't guarantee TX/RX channels write/read synchronously,
  *        they can only share the clock signals for now.
  * @note  If tx_handle OR rx_handle is NULL, it means this I2S controller will work at simplex mode.
- *        For ESP32 and ESP32S2, the whole I2S controller (i.e. both rx and tx channel) will be occupied,
- *        even if only one of rx or tx channel is registered.
+ *        For ESP32 and ESP32S2, the whole I2S controller (i.e. both RX and TX channel) will be occupied,
+ *        even if only one of RX or TX channel is registered.
  *        For the other targets, another channel on this controller will still available.
  *
  * @param[in]   chan_cfg    I2S controller channel configurations
@@ -106,8 +106,8 @@ typedef struct {
 esp_err_t i2s_new_channel(const i2s_chan_config_t *chan_cfg, i2s_chan_handle_t *ret_tx_handle, i2s_chan_handle_t *ret_rx_handle);
 
 /**
- * @brief Delete the i2s channel
- * @note  Only allowed to be called when the i2s channel is at REGISTERED or READY state (i.e., it should stop before deleting it).
+ * @brief Delete the I2S channel
+ * @note  Only allowed to be called when the I2S channel is at REGISTERED or READY state (i.e., it should stop before deleting it).
  * @note  Resource will be free automatically if all channels in one port are deleted
  *
  * @param[in]   handle      I2S channel handler
@@ -122,18 +122,18 @@ esp_err_t i2s_del_channel(i2s_chan_handle_t handle);
  * @param[in]   handle      I2S channel handler
  * @param[out]  chan_info   I2S channel basic information
  * @return
- *      - ESP_OK    Get i2s channel information success
- *      - ESP_ERR_NOT_FOUND     The input handle doesn't match any registered I2S channels, it may not an i2s channel handle or not available any more
+ *      - ESP_OK    Get I2S channel information success
+ *      - ESP_ERR_NOT_FOUND     The input handle doesn't match any registered I2S channels, it may not an I2S channel handle or not available any more
  *      - ESP_ERR_INVALID_ARG   The input handle or chan_info pointer is NULL
  */
 esp_err_t i2s_channel_get_info(i2s_chan_handle_t handle, i2s_chan_info_t *chan_info);
 
 /**
- * @brief Enable the i2s channel
+ * @brief Enable the I2S channel
  * @note  Only allowed to be called when the channel state is READY, (i.e., channel has been initialized, but not started)
  *        the channel will enter RUNNING state once it is enabled successfully.
- * @note  Enable the channel can start the I2S communication on hardware. It will start outputting bclk and ws signal.
- *        For mclk signal, it will start to output when initialization is finished
+ * @note  Enable the channel can start the I2S communication on hardware. It will start outputting BCLK and WS signal.
+ *        For MCLK signal, it will start to output when initialization is finished
  *
  * @param[in]   handle      I2S channel handler
  *      - ESP_OK    Start successfully
@@ -143,10 +143,10 @@ esp_err_t i2s_channel_get_info(i2s_chan_handle_t handle, i2s_chan_info_t *chan_i
 esp_err_t i2s_channel_enable(i2s_chan_handle_t handle);
 
 /**
- * @brief Disable the i2s channel
+ * @brief Disable the I2S channel
  * @note  Only allowed to be called when the channel state is RUNNING, (i.e., channel has been started)
  *        the channel will enter READY state once it is disabled successfully.
- * @note  Disable the channel can stop the I2S communication on hardware. It will stop bclk and ws signal but not mclk signal
+ * @note  Disable the channel can stop the I2S communication on hardware. It will stop BCLK and WS signal but not MCLK signal
  *
  * @param[in]   handle      I2S channel handler
  * @return
@@ -180,7 +180,7 @@ esp_err_t i2s_channel_preload_data(i2s_chan_handle_t tx_handle, const void *src,
 
 /**
  * @brief I2S write data
- * @note  Only allowed to be called when the channel state is RUNNING, (i.e., tx channel has been started and is not writing now)
+ * @note  Only allowed to be called when the channel state is RUNNING, (i.e., TX channel has been started and is not writing now)
  *        but the RUNNING only stands for the software state, it doesn't mean there is no the signal transporting on line.
  *
  * @param[in]   handle      I2S channel handler
@@ -190,7 +190,7 @@ esp_err_t i2s_channel_preload_data(i2s_chan_handle_t tx_handle, const void *src,
  * @param[in]   timeout_ms      Max block time
  * @return
  *      - ESP_OK    Write successfully
- *      - ESP_ERR_INVALID_ARG   NULL pointer or this handle is not tx handle
+ *      - ESP_ERR_INVALID_ARG   NULL pointer or this handle is not TX handle
  *      - ESP_ERR_TIMEOUT       Writing timeout, no writing event received from ISR within ticks_to_wait
  *      - ESP_ERR_INVALID_STATE I2S is not ready to write
  */
@@ -208,7 +208,7 @@ esp_err_t i2s_channel_write(i2s_chan_handle_t handle, const void *src, size_t si
  * @param[in]   timeout_ms      Max block time
  * @return
  *      - ESP_OK    Read successfully
- *      - ESP_ERR_INVALID_ARG   NULL pointer or this handle is not rx handle
+ *      - ESP_ERR_INVALID_ARG   NULL pointer or this handle is not RX handle
  *      - ESP_ERR_TIMEOUT       Reading timeout, no reading event received from ISR within ticks_to_wait
  *      - ESP_ERR_INVALID_STATE I2S is not ready to read
  */

components/driver/i2s/include/driver/i2s_pdm.h

@@ -7,7 +7,7 @@
 /**
  * This file is specified for I2S PDM communication mode
  * Features:
- *      - Only support PDM tx/rx mode
+ *      - Only support PDM TX/RX mode
  *      - Fixed to 2 slots
  *      - Data bit width only support 16 bits
  */
@@ -26,7 +26,7 @@ extern "C" {
 #if SOC_I2S_SUPPORTS_PDM_RX_HP_FILTER
 /**
  * @brief PDM format in 2 slots(RX)
- * @param bits_per_sample i2s data bit width, only support 16 bits for PDM mode
+ * @param bits_per_sample I2S data bit width, only support 16 bits for PDM mode
  * @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
  */
 #define I2S_PDM_RX_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo) { \
@@ -42,7 +42,7 @@ extern "C" {
 #else
 /**
  * @brief PDM format in 2 slots(RX)
- * @param bits_per_sample i2s data bit width, only support 16 bits for PDM mode
+ * @param bits_per_sample I2S data bit width, only support 16 bits for PDM mode
  * @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
  */
 #define I2S_PDM_RX_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo) { \
@@ -55,7 +55,7 @@ extern "C" {
 #endif  // SOC_I2S_SUPPORTS_PDM_RX_HP_FILTER
 
 /**
- * @brief i2s default pdm rx clock configuration
+ * @brief I2S default PDM RX clock configuration
  * @param rate sample rate
  */
 #define I2S_PDM_RX_CLK_DEFAULT_CONFIG(rate) { \
@@ -69,7 +69,7 @@ extern "C" {
 
 
 /**
- * @brief I2S slot configuration for pdm rx mode
+ * @brief I2S slot configuration for PDM RX mode
  */
 typedef struct {
     /* General fields */
@@ -82,7 +82,7 @@ typedef struct {
     bool                    hp_en;              /*!< High pass filter enable */
     float                   hp_cut_off_freq_hz; /*!< High pass filter cut-off frequency, range 23.3Hz ~ 185Hz, see cut-off frequency sheet above */
     uint32_t                amplify_num;        /*!< The amplification number of the final conversion result.
-                                                 *   The data that have converted from PDM to PCM module, will time 'amplify_num' additionally to amplify the final result.
+                                                 *   The data that have converted from PDM to PCM module, will time `amplify_num` additionally to amplify the final result.
                                                  *   Note that it's only a multiplier of the digital PCM data, not the gain of the analog signal
                                                  *   range 1~15, default 1 */
 #endif  // SOC_I2S_SUPPORTS_PDM_RX_HP_FILTER
@@ -90,21 +90,21 @@ typedef struct {
 } i2s_pdm_rx_slot_config_t;
 
 /**
- * @brief I2S clock configuration for pdm rx mode
+ * @brief I2S clock configuration for PDM RX mode
  */
 typedef struct {
     /* General fields */
     uint32_t                sample_rate_hz;     /*!< I2S sample rate */
     i2s_clock_src_t         clk_src;            /*!< Choose clock source */
-    i2s_mclk_multiple_t     mclk_multiple;      /*!< The multiple of mclk to the sample rate */
+    i2s_mclk_multiple_t     mclk_multiple;      /*!< The multiple of MCLK to the sample rate */
     /* Particular fields */
     i2s_pdm_dsr_t           dn_sample_mode;     /*!< Down-sampling rate mode */
-    uint32_t                bclk_div;           /*!< The division from mclk to bclk. The typical and minimum value is I2S_PDM_RX_BCLK_DIV_MIN.
+    uint32_t                bclk_div;           /*!< The division from MCLK to BCLK. The typical and minimum value is I2S_PDM_RX_BCLK_DIV_MIN.
                                                  *   It will be set to I2S_PDM_RX_BCLK_DIV_MIN by default if it is smaller than I2S_PDM_RX_BCLK_DIV_MIN */
 } i2s_pdm_rx_clk_config_t;
 
 /**
- * @brief I2S PDM tx mode GPIO pins configuration
+ * @brief I2S PDM TX mode GPIO pins configuration
  */
 typedef struct {
     gpio_num_t clk;                                     /*!< PDM clk pin, output */
@@ -118,7 +118,7 @@ typedef struct {
 } i2s_pdm_rx_gpio_config_t;
 
 /**
- * @brief I2S PDM RX mode major configuration that including clock/slot/gpio configuration
+ * @brief I2S PDM RX mode major configuration that including clock/slot/GPIO configuration
  */
 typedef struct {
     i2s_pdm_rx_clk_config_t    clk_cfg;         /*!< PDM RX clock configurations, can be generated by macro I2S_PDM_RX_CLK_DEFAULT_CONFIG */
@@ -127,12 +127,12 @@ typedef struct {
 } i2s_pdm_rx_config_t;
 
 /**
- * @brief Initialize i2s channel to PDM RX mode
+ * @brief Initialize I2S channel to PDM RX mode
  * @note  Only allowed to be called when the channel state is REGISTERED, (i.e., channel has been allocated, but not initialized)
  *        and the state will be updated to READY if initialization success, otherwise the state will return to REGISTERED.
  *
- * @param[in]   handle      I2S rx channel handler
- * @param[in]   pdm_rx_cfg  Configurations for PDM RX mode, including clock, slot and gpio
+ * @param[in]   handle      I2S RX channel handler
+ * @param[in]   pdm_rx_cfg  Configurations for PDM RX mode, including clock, slot and GPIO
  *                          The clock configuration can be generated by the helper macro `I2S_PDM_RX_CLK_DEFAULT_CONFIG`
  *                          The slot configuration can be generated by the helper macro `I2S_PDM_RX_SLOT_DEFAULT_CONFIG`
  *
@@ -147,10 +147,10 @@ esp_err_t i2s_channel_init_pdm_rx_mode(i2s_chan_handle_t handle, const i2s_pdm_r
 /**
  * @brief Reconfigure the I2S clock for PDM RX mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
- *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to PDM RX mode, i.e., 'i2s_channel_init_pdm_rx_mode' has been called before reconfiguring
+ *        this function won't change the state. `i2s_channel_disable` should be called before calling this function if I2S has started.
+ * @note  The input channel handle has to be initialized to PDM RX mode, i.e., `i2s_channel_init_pdm_rx_mode` has been called before reconfiguring
  *
- * @param[in]   handle      I2S rx channel handler
+ * @param[in]   handle      I2S RX channel handler
  * @param[in]   clk_cfg     PDM RX mode clock configuration, can be generated by `I2S_PDM_RX_CLK_DEFAULT_CONFIG`
  * @return
  *      - ESP_OK    Set clock successfully
@@ -162,10 +162,10 @@ esp_err_t i2s_channel_reconfig_pdm_rx_clock(i2s_chan_handle_t handle, const i2s_
 /**
  * @brief Reconfigure the I2S slot for PDM RX mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
- *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to PDM RX mode, i.e., 'i2s_channel_init_pdm_rx_mode' has been called before reconfiguring
+ *        this function won't change the state. `i2s_channel_disable` should be called before calling this function if I2S has started.
+ * @note  The input channel handle has to be initialized to PDM RX mode, i.e., `i2s_channel_init_pdm_rx_mode` has been called before reconfiguring
  *
- * @param[in]   handle      I2S rx channel handler
+ * @param[in]   handle      I2S RX channel handler
  * @param[in]   slot_cfg    PDM RX mode slot configuration, can be generated by `I2S_PDM_RX_SLOT_DEFAULT_CONFIG`
  * @return
  *      - ESP_OK    Set clock successfully
@@ -176,13 +176,13 @@ esp_err_t i2s_channel_reconfig_pdm_rx_clock(i2s_chan_handle_t handle, const i2s_
 esp_err_t i2s_channel_reconfig_pdm_rx_slot(i2s_chan_handle_t handle, const i2s_pdm_rx_slot_config_t *slot_cfg);
 
 /**
- * @brief Reconfigure the I2S gpio for PDM RX mode
+ * @brief Reconfigure the I2S GPIO for PDM RX mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
- *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to PDM RX mode, i.e., 'i2s_channel_init_pdm_rx_mode' has been called before reconfiguring
+ *        this function won't change the state. `i2s_channel_disable` should be called before calling this function if I2S has started.
+ * @note  The input channel handle has to be initialized to PDM RX mode, i.e., `i2s_channel_init_pdm_rx_mode` has been called before reconfiguring
  *
- * @param[in]   handle      I2S rx channel handler
- * @param[in]   gpio_cfg    PDM RX mode gpio configuration, specified by user
+ * @param[in]   handle      I2S RX channel handler
+ * @param[in]   gpio_cfg    PDM RX mode GPIO configuration, specified by user
  * @return
  *      - ESP_OK    Set clock successfully
  *      - ESP_ERR_INVALID_ARG   NULL pointer, invalid configuration  or not PDM mode
@@ -198,7 +198,7 @@ esp_err_t i2s_channel_reconfig_pdm_rx_gpio(i2s_chan_handle_t handle, const i2s_p
 #if SOC_I2S_HW_VERSION_2
 /**
  * @brief PDM style in 2 slots(TX) for codec line mode
- * @param bits_per_sample i2s data bit width, only support 16 bits for PDM mode
+ * @param bits_per_sample I2S data bit width, only support 16 bits for PDM mode
  * @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
  */
 #define I2S_PDM_TX_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo) { \
@@ -221,7 +221,7 @@ esp_err_t i2s_channel_reconfig_pdm_rx_gpio(i2s_chan_handle_t handle, const i2s_p
  * @brief PDM style in 1 slots(TX) for DAC line mode
  * @note The noise might be different with different configurations, this macro provides a set of configurations
  *       that have relatively high SNR (Signal Noise Ratio), you can also adjust them to fit your case.
- * @param bits_per_sample i2s data bit width, only support 16 bits for PDM mode
+ * @param bits_per_sample I2S data bit width, only support 16 bits for PDM mode
  * @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
  */
 #define I2S_PDM_TX_SLOT_DAC_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo) { \
@@ -243,7 +243,7 @@ esp_err_t i2s_channel_reconfig_pdm_rx_gpio(i2s_chan_handle_t handle, const i2s_p
 #else // SOC_I2S_HW_VERSION_2
 /**
  * @brief PDM style in 2 slots(TX) for codec line mode
- * @param bits_per_sample i2s data bit width, only support 16 bits for PDM mode
+ * @param bits_per_sample I2S data bit width, only support 16 bits for PDM mode
  * @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
  */
 #define I2S_PDM_TX_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo) { \
@@ -260,11 +260,11 @@ esp_err_t i2s_channel_reconfig_pdm_rx_gpio(i2s_chan_handle_t handle, const i2s_p
 #endif // SOC_I2S_HW_VERSION_2
 
 /**
- * @brief i2s default pdm tx clock configuration for codec line mode
+ * @brief I2S default PDM TX clock configuration for codec line mode
  * @note TX PDM can only be set to the following two up-sampling rate configurations:
  *       1: fp = 960, fs = sample_rate_hz / 100, in this case, Fpdm = 128*48000
  *       2: fp = 960, fs = 480, in this case, Fpdm = 128*Fpcm = 128*sample_rate_hz
- *       If the pdm receiver do not care the pdm serial clock, it's recommended set Fpdm = 128*48000.
+ *       If the PDM receiver do not care the PDM serial clock, it's recommended set Fpdm = 128*48000.
  *       Otherwise, the second configuration should be adopted.
  * @param rate sample rate (not suggest to exceed 48000 Hz, otherwise more glitches and noise may appear)
  */
@@ -278,11 +278,11 @@ esp_err_t i2s_channel_reconfig_pdm_rx_gpio(i2s_chan_handle_t handle, const i2s_p
 }
 
 /**
- * @brief i2s default pdm tx clock configuration for DAC line mode
+ * @brief I2S default PDM TX clock configuration for DAC line mode
  * @note TX PDM can only be set to the following two up-sampling rate configurations:
  *       1: fp = 960, fs = sample_rate_hz / 100, in this case, Fpdm = 128*48000
  *       2: fp = 960, fs = 480, in this case, Fpdm = 128*Fpcm = 128*sample_rate_hz
- *       If the pdm receiver do not care the pdm serial clock, it's recommended set Fpdm = 128*48000.
+ *       If the PDM receiver do not care the PDM serial clock, it's recommended set Fpdm = 128*48000.
  *       Otherwise, the second configuration should be adopted.
  * @note The noise might be different with different configurations, this macro provides a set of configurations
  *       that have relatively high SNR (Signal Noise Ratio), you can also adjust them to fit your case.
@@ -313,7 +313,7 @@ esp_err_t i2s_channel_reconfig_pdm_rx_gpio(i2s_chan_handle_t handle, const i2s_p
  */
 
 /**
- * @brief I2S slot configuration for pdm tx mode
+ * @brief I2S slot configuration for PDM TX mode
  */
 typedef struct {
     /* General fields */
@@ -342,22 +342,22 @@ typedef struct {
 } i2s_pdm_tx_slot_config_t;
 
 /**
- * @brief I2S clock configuration for pdm tx mode
+ * @brief I2S clock configuration for PDM TX mode
  */
 typedef struct {
     /* General fields */
     uint32_t                sample_rate_hz;     /*!< I2S sample rate, not suggest to exceed 48000 Hz, otherwise more glitches and noise may appear */
     i2s_clock_src_t         clk_src;            /*!< Choose clock source */
-    i2s_mclk_multiple_t     mclk_multiple;      /*!< The multiple of mclk to the sample rate */
+    i2s_mclk_multiple_t     mclk_multiple;      /*!< The multiple of MCLK to the sample rate */
     /* Particular fields */
     uint32_t                up_sample_fp;       /*!< Up-sampling param fp */
     uint32_t                up_sample_fs;       /*!< Up-sampling param fs, not allowed to be greater than 480 */
-    uint32_t                bclk_div;           /*!< The division from mclk to bclk. The minimum value is I2S_PDM_TX_BCLK_DIV_MIN.
+    uint32_t                bclk_div;           /*!< The division from MCLK to BCLK. The minimum value is I2S_PDM_TX_BCLK_DIV_MIN.
                                                  *   It will be set to I2S_PDM_TX_BCLK_DIV_MIN by default if it is smaller than I2S_PDM_TX_BCLK_DIV_MIN */
 } i2s_pdm_tx_clk_config_t;
 
 /**
- * @brief I2S PDM tx mode GPIO pins configuration
+ * @brief I2S PDM TX mode GPIO pins configuration
  */
 typedef struct {
     gpio_num_t clk;                /*!< PDM clk pin, output */
@@ -373,21 +373,21 @@ typedef struct {
 } i2s_pdm_tx_gpio_config_t;
 
 /**
- * @brief I2S PDM TX mode major configuration that including clock/slot/gpio configuration
+ * @brief I2S PDM TX mode major configuration that including clock/slot/GPIO configuration
  */
 typedef struct {
     i2s_pdm_tx_clk_config_t    clk_cfg;         /*!< PDM TX clock configurations, can be generated by macro I2S_PDM_TX_CLK_DEFAULT_CONFIG */
     i2s_pdm_tx_slot_config_t   slot_cfg;        /*!< PDM TX slot configurations, can be generated by macro I2S_PDM_TX_SLOT_DEFAULT_CONFIG */
-    i2s_pdm_tx_gpio_config_t   gpio_cfg;        /*!< PDM TX gpio configurations, specified by user */
+    i2s_pdm_tx_gpio_config_t   gpio_cfg;        /*!< PDM TX GPIO configurations, specified by user */
 } i2s_pdm_tx_config_t;
 
 /**
- * @brief Initialize i2s channel to PDM TX mode
+ * @brief Initialize I2S channel to PDM TX mode
  * @note  Only allowed to be called when the channel state is REGISTERED, (i.e., channel has been allocated, but not initialized)
  *        and the state will be updated to READY if initialization success, otherwise the state will return to REGISTERED.
  *
- * @param[in]   handle      I2S tx channel handler
- * @param[in]   pdm_tx_cfg  Configurations for PDM TX mode, including clock, slot and gpio
+ * @param[in]   handle      I2S TX channel handler
+ * @param[in]   pdm_tx_cfg  Configurations for PDM TX mode, including clock, slot and GPIO
  *                          The clock configuration can be generated by the helper macro `I2S_PDM_TX_CLK_DEFAULT_CONFIG`
  *                          The slot configuration can be generated by the helper macro `I2S_PDM_TX_SLOT_DEFAULT_CONFIG`
  *
@@ -402,10 +402,10 @@ esp_err_t i2s_channel_init_pdm_tx_mode(i2s_chan_handle_t handle, const i2s_pdm_t
 /**
  * @brief Reconfigure the I2S clock for PDM TX mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
- *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to PDM TX mode, i.e., 'i2s_channel_init_pdm_tx_mode' has been called before reconfiguring
+ *        this function won't change the state. `i2s_channel_disable` should be called before calling this function if I2S has started.
+ * @note  The input channel handle has to be initialized to PDM TX mode, i.e., `i2s_channel_init_pdm_tx_mode` has been called before reconfiguring
  *
- * @param[in]   handle      I2S tx channel handler
+ * @param[in]   handle      I2S TX channel handler
  * @param[in]   clk_cfg     PDM TX mode clock configuration, can be generated by `I2S_PDM_TX_CLK_DEFAULT_CONFIG`
  * @return
  *      - ESP_OK    Set clock successfully
@@ -417,10 +417,10 @@ esp_err_t i2s_channel_reconfig_pdm_tx_clock(i2s_chan_handle_t handle, const i2s_
 /**
  * @brief Reconfigure the I2S slot for PDM TX mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
- *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to PDM TX mode, i.e., 'i2s_channel_init_pdm_tx_mode' has been called before reconfiguring
+ *        this function won't change the state. `i2s_channel_disable` should be called before calling this function if I2S has started.
+ * @note  The input channel handle has to be initialized to PDM TX mode, i.e., `i2s_channel_init_pdm_tx_mode` has been called before reconfiguring
  *
- * @param[in]   handle      I2S tx channel handler
+ * @param[in]   handle      I2S TX channel handler
  * @param[in]   slot_cfg    PDM TX mode slot configuration, can be generated by `I2S_PDM_TX_SLOT_DEFAULT_CONFIG`
  * @return
  *      - ESP_OK    Set clock successfully
@@ -431,13 +431,13 @@ esp_err_t i2s_channel_reconfig_pdm_tx_clock(i2s_chan_handle_t handle, const i2s_
 esp_err_t i2s_channel_reconfig_pdm_tx_slot(i2s_chan_handle_t handle, const i2s_pdm_tx_slot_config_t *slot_cfg);
 
 /**
- * @brief Reconfigure the I2S gpio for PDM TX mode
+ * @brief Reconfigure the I2S GPIO for PDM TX mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
- *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to PDM TX mode, i.e., 'i2s_channel_init_pdm_tx_mode' has been called before reconfiguring
+ *        this function won't change the state. `i2s_channel_disable` should be called before calling this function if I2S has started.
+ * @note  The input channel handle has to be initialized to PDM TX mode, i.e., `i2s_channel_init_pdm_tx_mode` has been called before reconfiguring
  *
- * @param[in]   handle      I2S tx channel handler
- * @param[in]   gpio_cfg    PDM TX mode gpio configuration, specified by user
+ * @param[in]   handle      I2S TX channel handler
+ * @param[in]   gpio_cfg    PDM TX mode GPIO configuration, specified by user
  * @return
  *      - ESP_OK    Set clock successfully
  *      - ESP_ERR_INVALID_ARG   NULL pointer, invalid configuration  or not PDM mode

components/driver/i2s/include/driver/i2s_std.h

@@ -25,7 +25,7 @@ extern "C" {
 #if CONFIG_IDF_TARGET_ESP32
 /**
  * @brief Philips format in 2 slots
- * @param bits_per_sample i2s data bit width
+ * @param bits_per_sample I2S data bit width
  * @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
  */
 #define I2S_STD_PHILIPS_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo) { \
@@ -43,8 +43,8 @@ extern "C" {
 
 /**
  * @brief PCM(short) format in 2 slots
- * @note  PCM(long) is same as philips in 2 slots
- * @param bits_per_sample i2s data bit width
+ * @note  PCM(long) is same as Philips in 2 slots
+ * @param bits_per_sample I2S data bit width
  * @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
  */
 #define I2S_STD_PCM_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo)  { \
@@ -62,7 +62,7 @@ extern "C" {
 
 /**
  * @brief MSB format in 2 slots
- * @param bits_per_sample i2s data bit width
+ * @param bits_per_sample I2S data bit width
  * @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
  */
 #define I2S_STD_MSB_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo) { \
@@ -81,7 +81,7 @@ extern "C" {
 #elif CONFIG_IDF_TARGET_ESP32S2
 /**
  * @brief Philips format in 2 slots
- * @param bits_per_sample i2s data bit width
+ * @param bits_per_sample I2S data bit width
  * @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
  */
 #define I2S_STD_PHILIPS_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo) { \
@@ -98,8 +98,8 @@ extern "C" {
 
 /**
  * @brief PCM(short) format in 2 slots
- * @note  PCM(long) is same as philips in 2 slots
- * @param bits_per_sample i2s data bit width
+ * @note  PCM(long) is same as Philips in 2 slots
+ * @param bits_per_sample I2S data bit width
  * @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
  */
 #define I2S_STD_PCM_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo)  { \
@@ -116,7 +116,7 @@ extern "C" {
 
 /**
  * @brief MSB format in 2 slots
- * @param bits_per_sample i2s data bit width
+ * @param bits_per_sample I2S data bit width
  * @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
  */
 #define I2S_STD_MSB_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo) { \
@@ -134,7 +134,7 @@ extern "C" {
 #else
 /**
  * @brief Philips format in 2 slots
- * @param bits_per_sample i2s data bit width
+ * @param bits_per_sample I2S data bit width
  * @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
  */
 #define I2S_STD_PHILIPS_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo) { \
@@ -152,8 +152,8 @@ extern "C" {
 
 /**
  * @brief PCM(short) format in 2 slots
- * @note  PCM(long) is same as philips in 2 slots
- * @param bits_per_sample i2s data bit width
+ * @note  PCM(long) is same as Philips in 2 slots
+ * @param bits_per_sample I2S data bit width
  * @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
  */
 #define I2S_STD_PCM_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo)  { \
@@ -171,7 +171,7 @@ extern "C" {
 
 /**
  * @brief MSB format in 2 slots
- * @param bits_per_sample i2s data bit width
+ * @param bits_per_sample I2S data bit width
  * @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
  */
 #define I2S_STD_MSB_SLOT_DEFAULT_CONFIG(bits_per_sample, mono_or_stereo) { \
@@ -194,9 +194,9 @@ extern "C" {
 /** @endcond */
 
 /**
- * @brief i2s default standard clock configuration
+ * @brief I2S default standard clock configuration
  * @note Please set the mclk_multiple to I2S_MCLK_MULTIPLE_384 while using 24 bits data width
- *       Otherwise the sample rate might be imprecise since the bclk division is not a integer
+ *       Otherwise the sample rate might be imprecise since the BCLK division is not a integer
  * @param rate sample rate
  */
 #define I2S_STD_CLK_DEFAULT_CONFIG(rate) { \
@@ -219,7 +219,7 @@ typedef struct {
 
     /* Particular fields */
     i2s_std_slot_mask_t     slot_mask;          /*!< Select the left, right or both slot */
-    uint32_t                ws_width;           /*!< WS signal width (i.e. the number of bclk ticks that ws signal is high) */
+    uint32_t                ws_width;           /*!< WS signal width (i.e. the number of BCLK ticks that WS signal is high) */
     bool                    ws_pol;             /*!< WS signal polarity, set true to enable high lever first */
     bool                    bit_shift;          /*!< Set to enable bit shift in Philips mode */
 #if SOC_I2S_HW_VERSION_1    // For esp32/esp32-s2
@@ -237,17 +237,17 @@ typedef struct {
 typedef struct {
     /* General fields */
     uint32_t                sample_rate_hz;     /*!< I2S sample rate */
-    i2s_clock_src_t         clk_src;            /*!< Choose clock source, see 'soc_periph_i2s_clk_src_t' for the supported clock sources.
-                                                 *   selected 'I2S_CLK_SRC_EXTERNAL'(if supports) to enable the external source clock input via MCLK pin,
+    i2s_clock_src_t         clk_src;            /*!< Choose clock source, see `soc_periph_i2s_clk_src_t` for the supported clock sources.
+                                                 *   selected `I2S_CLK_SRC_EXTERNAL` (if supports) to enable the external source clock input via MCLK pin,
                                                  */
 #if SOC_I2S_HW_VERSION_2
-    uint32_t                ext_clk_freq_hz;    /*!< External clock source frequency in Hz, only take effect when 'clk_src = I2S_CLK_SRC_EXTERNAL', otherwise this field will be ignored,
-                                                 *   Please make sure the frequency input is equal or greater than bclk, i.e. 'sample_rate_hz * slot_bits * 2'
+    uint32_t                ext_clk_freq_hz;    /*!< External clock source frequency in Hz, only take effect when `clk_src = I2S_CLK_SRC_EXTERNAL`, otherwise this field will be ignored,
+                                                 *   Please make sure the frequency input is equal or greater than BCLK, i.e. `sample_rate_hz * slot_bits * 2`
                                                  */
 #endif
-    i2s_mclk_multiple_t     mclk_multiple;      /*!< The multiple of mclk to the sample rate
+    i2s_mclk_multiple_t     mclk_multiple;      /*!< The multiple of MCLK to the sample rate
                                                  *   Default is 256 in the helper macro, it can satisfy most of cases,
-                                                 *   but please set this field a multiple of '3' (like 384) when using 24-bit data width,
+                                                 *   but please set this field a multiple of `3` (like 384) when using 24-bit data width,
                                                  *   otherwise the sample rate might be inaccurate
                                                  */
 } i2s_std_clk_config_t;
@@ -256,34 +256,34 @@ typedef struct {
  * @brief I2S standard mode GPIO pins configuration
  */
 typedef struct {
-    gpio_num_t mclk;               /*!< MCK pin, output by default, input if the clock source is selected to 'I2S_CLK_SRC_EXTERNAL' */
-    gpio_num_t bclk;               /*!< BCK pin, input in slave role, output in master role */
-    gpio_num_t ws;                 /*!< WS pin, input in slave role, output in master role */
+    gpio_num_t MCLK;               /*!< MCK pin, output by default, input if the clock source is selected to `I2S_CLK_SRC_EXTERNAL` */
+    gpio_num_t BCLK;               /*!< BCK pin, input in slave role, output in master role */
+    gpio_num_t WS;                 /*!< WS pin, input in slave role, output in master role */
     gpio_num_t dout;               /*!< DATA pin, output */
     gpio_num_t din;                /*!< DATA pin, input */
     struct {
-        uint32_t   mclk_inv: 1;    /*!< Set 1 to invert the mclk output */
-        uint32_t   bclk_inv: 1;    /*!< Set 1 to invert the bclk input/output */
-        uint32_t   ws_inv: 1;      /*!< Set 1 to invert the ws input/output */
+        uint32_t   mclk_inv: 1;    /*!< Set 1 to invert the MCLK output */
+        uint32_t   bclk_inv: 1;    /*!< Set 1 to invert the BCLK input/output */
+        uint32_t   ws_inv: 1;      /*!< Set 1 to invert the WS input/output */
     } invert_flags;                /*!< GPIO pin invert flags */
 } i2s_std_gpio_config_t;
 
 /**
- * @brief I2S standard mode major configuration that including clock/slot/gpio configuration
+ * @brief I2S standard mode major configuration that including clock/slot/GPIO configuration
  */
 typedef struct {
     i2s_std_clk_config_t    clk_cfg;    /*!< Standard mode clock configuration, can be generated by macro I2S_STD_CLK_DEFAULT_CONFIG */
     i2s_std_slot_config_t   slot_cfg;   /*!< Standard mode slot configuration, can be generated by macros I2S_STD_[mode]_SLOT_DEFAULT_CONFIG, [mode] can be replaced with PHILIPS/MSB/PCM */
-    i2s_std_gpio_config_t   gpio_cfg;   /*!< Standard mode gpio configuration, specified by user */
+    i2s_std_gpio_config_t   gpio_cfg;   /*!< Standard mode GPIO configuration, specified by user */
 } i2s_std_config_t;
 
 /**
- * @brief Initialize i2s channel to standard mode
+ * @brief Initialize I2S channel to standard mode
  * @note  Only allowed to be called when the channel state is REGISTERED, (i.e., channel has been allocated, but not initialized)
  *        and the state will be updated to READY if initialization success, otherwise the state will return to REGISTERED.
  *
  * @param[in]   handle      I2S channel handler
- * @param[in]   std_cfg     Configurations for standard mode, including clock, slot and gpio
+ * @param[in]   std_cfg     Configurations for standard mode, including clock, slot and GPIO
  *                          The clock configuration can be generated by the helper macro `I2S_STD_CLK_DEFAULT_CONFIG`
  *                          The slot configuration can be generated by the helper macro `I2S_STD_PHILIPS_SLOT_DEFAULT_CONFIG`,
  *                          `I2S_STD_PCM_SLOT_DEFAULT_CONFIG` or `I2S_STD_MSB_SLOT_DEFAULT_CONFIG`
@@ -299,8 +299,8 @@ esp_err_t i2s_channel_init_std_mode(i2s_chan_handle_t handle, const i2s_std_conf
 /**
  * @brief Reconfigure the I2S clock for standard mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
- *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to standard mode, i.e., 'i2s_channel_init_std_mode' has been called before reconfiguring
+ *        this function won't change the state. `i2s_channel_disable` should be called before calling this function if I2S has started.
+ * @note  The input channel handle has to be initialized to standard mode, i.e., `i2s_channel_init_std_mode` has been called before reconfiguring
  *
  * @param[in]   handle      I2S channel handler
  * @param[in]   clk_cfg     Standard mode clock configuration, can be generated by `I2S_STD_CLK_DEFAULT_CONFIG`
@@ -314,8 +314,8 @@ esp_err_t i2s_channel_reconfig_std_clock(i2s_chan_handle_t handle, const i2s_std
 /**
  * @brief Reconfigure the I2S slot for standard mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
- *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to standard mode, i.e., 'i2s_channel_init_std_mode' has been called before reconfiguring
+ *        this function won't change the state. `i2s_channel_disable` should be called before calling this function if I2S has started.
+ * @note  The input channel handle has to be initialized to standard mode, i.e., `i2s_channel_init_std_mode` has been called before reconfiguring
  *
  * @param[in]   handle      I2S channel handler
  * @param[in]   slot_cfg    Standard mode slot configuration, can be generated by `I2S_STD_PHILIPS_SLOT_DEFAULT_CONFIG`,
@@ -329,13 +329,13 @@ esp_err_t i2s_channel_reconfig_std_clock(i2s_chan_handle_t handle, const i2s_std
 esp_err_t i2s_channel_reconfig_std_slot(i2s_chan_handle_t handle, const i2s_std_slot_config_t *slot_cfg);
 
 /**
- * @brief Reconfigure the I2S gpio for standard mode
+ * @brief Reconfigure the I2S GPIO for standard mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
- *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to standard mode, i.e., 'i2s_channel_init_std_mode' has been called before reconfiguring
+ *        this function won't change the state. `i2s_channel_disable` should be called before calling this function if I2S has started.
+ * @note  The input channel handle has to be initialized to standard mode, i.e., `i2s_channel_init_std_mode` has been called before reconfiguring
  *
  * @param[in]   handle      I2S channel handler
- * @param[in]   gpio_cfg    Standard mode gpio configuration, specified by user
+ * @param[in]   gpio_cfg    Standard mode GPIO configuration, specified by user
  * @return
  *      - ESP_OK    Set clock successfully
  *      - ESP_ERR_INVALID_ARG   NULL pointer, invalid configuration  or not standard mode

components/driver/i2s/include/driver/i2s_tdm.h

@@ -22,11 +22,11 @@ extern "C" {
 #endif
 
 #define I2S_TDM_AUTO_SLOT_NUM    (0)       // Auto means total slot number will be equal to the maximum active slot number
-#define I2S_TDM_AUTO_WS_WIDTH    (0)       // Auto means ws signal width will be equal to the half width of a frame
+#define I2S_TDM_AUTO_WS_WIDTH    (0)       // Auto means WS signal width will be equal to the half width of a frame
 
 /**
  * @brief Philips format in active slot that enabled by mask
- * @param bits_per_sample i2s data bit width
+ * @param bits_per_sample I2S data bit width
  * @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
  * @param mask active slot mask
  */
@@ -47,7 +47,7 @@ extern "C" {
 
 /**
  * @brief MSB format in active slot enabled that by mask
- * @param bits_per_sample i2s data bit width
+ * @param bits_per_sample I2S data bit width
  * @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
  * @param mask active slot mask
  */
@@ -68,7 +68,7 @@ extern "C" {
 
 /**
  * @brief PCM(short) format in active slot that enabled by mask
- * @param bits_per_sample i2s data bit width
+ * @param bits_per_sample I2S data bit width
  * @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
  * @param mask active slot mask
  */
@@ -89,7 +89,7 @@ extern "C" {
 
 /**
  * @brief PCM(long) format in active slot that enabled by mask
- * @param bits_per_sample i2s data bit width
+ * @param bits_per_sample I2S data bit width
  * @param mono_or_stereo I2S_SLOT_MODE_MONO or I2S_SLOT_MODE_STEREO
  * @param mask active slot mask
  */
@@ -115,9 +115,9 @@ extern "C" {
 
 
 /**
- * @brief i2s default tdm clock configuration
+ * @brief I2S default TDM clock configuration
  * @note Please set the mclk_multiple to I2S_MCLK_MULTIPLE_384 while the data width in slot configuration is set to 24 bits
- *       Otherwise the sample rate might be imprecise since the bclk division is not a integer
+ *       Otherwise the sample rate might be imprecise since the BCLK division is not a integer
  * @param rate sample rate
  */
 #define I2S_TDM_CLK_DEFAULT_CONFIG(rate) { \
@@ -128,7 +128,7 @@ extern "C" {
 }
 
 /**
- * @brief I2S slot configuration for tdm mode
+ * @brief I2S slot configuration for TDM mode
  */
 typedef struct {
     /* General fields */
@@ -138,7 +138,7 @@ typedef struct {
 
     /* Particular fields */
     i2s_tdm_slot_mask_t     slot_mask;          /*!< Slot mask. Activating slots by setting 1 to corresponding bits. When the activated slots is not consecutive, those data in inactivated slots will be ignored */
-    uint32_t                ws_width;           /*!< WS signal width (i.e. the number of bclk ticks that ws signal is high) */
+    uint32_t                ws_width;           /*!< WS signal width (i.e. the number of BCLK ticks that WS signal is high) */
     bool                    ws_pol;             /*!< WS signal polarity, set true to enable high lever first */
     bool                    bit_shift;          /*!< Set true to enable bit shift in Philips mode */
 
@@ -151,54 +151,54 @@ typedef struct {
 } i2s_tdm_slot_config_t;
 
 /**
- * @brief I2S clock configuration for tdm mode
+ * @brief I2S clock configuration for TDM mode
  */
 typedef struct {
     /* General fields */
     uint32_t                sample_rate_hz;     /*!< I2S sample rate */
-    i2s_clock_src_t         clk_src;            /*!< Choose clock source, see 'soc_periph_i2s_clk_src_t' for the supported clock sources.
-                                                 *   selected 'I2S_CLK_SRC_EXTERNAL'(if supports) to enable the external source clock inputted via MCLK pin,
-                                                 *   please make sure the frequency inputted is equal or greater than 'sample_rate_hz * mclk_multiple'
+    i2s_clock_src_t         clk_src;            /*!< Choose clock source, see `soc_periph_i2s_clk_src_t` for the supported clock sources.
+                                                 *   selected `I2S_CLK_SRC_EXTERNAL` (if supports) to enable the external source clock inputted via MCLK pin,
+                                                 *   please make sure the frequency inputted is equal or greater than `sample_rate_hz * mclk_multiple`
                                                  */
-    uint32_t                ext_clk_freq_hz;    /*!< External clock source frequency in Hz, only take effect when 'clk_src = I2S_CLK_SRC_EXTERNAL', otherwise this field will be ignored
-                                                 *   Please make sure the frequency inputted is equal or greater than bclk, i.e. 'sample_rate_hz * slot_bits * slot_num'
+    uint32_t                ext_clk_freq_hz;    /*!< External clock source frequency in Hz, only take effect when `clk_src = I2S_CLK_SRC_EXTERNAL`, otherwise this field will be ignored
+                                                 *   Please make sure the frequency inputted is equal or greater than BCLK, i.e. `sample_rate_hz * slot_bits * slot_num`
                                                  */
-    i2s_mclk_multiple_t     mclk_multiple;      /*!< The multiple of mclk to the sample rate, only take effect for master role */
-    uint32_t                bclk_div;           /*!< The division from mclk to bclk, only take effect for slave role, it shouldn't be smaller than 8. Increase this field when data sent by slave lag behind */
+    i2s_mclk_multiple_t     mclk_multiple;      /*!< The multiple of MCLK to the sample rate, only take effect for master role */
+    uint32_t                bclk_div;           /*!< The division from MCLK to BCLK, only take effect for slave role, it shouldn't be smaller than 8. Increase this field when data sent by slave lag behind */
 } i2s_tdm_clk_config_t;
 
 /**
  * @brief I2S TDM mode GPIO pins configuration
  */
 typedef struct {
-    gpio_num_t mclk;               /*!< MCK pin, output by default, input if the clock source is selected to 'I2S_CLK_SRC_EXTERNAL' */
-    gpio_num_t bclk;               /*!< BCK pin, input in slave role, output in master role */
-    gpio_num_t ws;                 /*!< WS pin, input in slave role, output in master role */
+    gpio_num_t MCLK;               /*!< MCK pin, output by default, input if the clock source is selected to `I2S_CLK_SRC_EXTERNAL` */
+    gpio_num_t BCLK;               /*!< BCK pin, input in slave role, output in master role */
+    gpio_num_t WS;                 /*!< WS pin, input in slave role, output in master role */
     gpio_num_t dout;               /*!< DATA pin, output */
     gpio_num_t din;                /*!< DATA pin, input */
     struct {
-        uint32_t   mclk_inv: 1;    /*!< Set 1 to invert the mclk output */
-        uint32_t   bclk_inv: 1;    /*!< Set 1 to invert the bclk input/output */
-        uint32_t   ws_inv: 1;      /*!< Set 1 to invert the ws input/output */
+        uint32_t   mclk_inv: 1;    /*!< Set 1 to invert the MCLK output */
+        uint32_t   bclk_inv: 1;    /*!< Set 1 to invert the BCLK input/output */
+        uint32_t   ws_inv: 1;      /*!< Set 1 to invert the WS input/output */
     } invert_flags;                /*!< GPIO pin invert flags */
 } i2s_tdm_gpio_config_t;
 
 /**
- * @brief I2S TDM mode major configuration that including clock/slot/gpio configuration
+ * @brief I2S TDM mode major configuration that including clock/slot/GPIO configuration
  */
 typedef struct {
     i2s_tdm_clk_config_t    clk_cfg;    /*!< TDM mode clock configuration, can be generated by macro I2S_TDM_CLK_DEFAULT_CONFIG */
     i2s_tdm_slot_config_t   slot_cfg;   /*!< TDM mode slot configuration, can be generated by macros I2S_TDM_[mode]_SLOT_DEFAULT_CONFIG, [mode] can be replaced with PHILIPS/MSB/PCM_SHORT/PCM_LONG */
-    i2s_tdm_gpio_config_t   gpio_cfg;   /*!< TDM mode gpio configuration, specified by user */
+    i2s_tdm_gpio_config_t   gpio_cfg;   /*!< TDM mode GPIO configuration, specified by user */
 } i2s_tdm_config_t;
 
 /**
- * @brief Initialize i2s channel to TDM mode
+ * @brief Initialize I2S channel to TDM mode
  * @note  Only allowed to be called when the channel state is REGISTERED, (i.e., channel has been allocated, but not initialized)
  *        and the state will be updated to READY if initialization success, otherwise the state will return to REGISTERED.
  *
  * @param[in]   handle      I2S channel handler
- * @param[in]   tdm_cfg     Configurations for TDM mode, including clock, slot and gpio
+ * @param[in]   tdm_cfg     Configurations for TDM mode, including clock, slot and GPIO
  *                          The clock configuration can be generated by the helper macro `I2S_TDM_CLK_DEFAULT_CONFIG`
  *                          The slot configuration can be generated by the helper macro `I2S_TDM_PHILIPS_SLOT_DEFAULT_CONFIG`,
  *                          `I2S_TDM_PCM_SHORT_SLOT_DEFAULT_CONFIG`, `I2S_TDM_PCM_LONG_SLOT_DEFAULT_CONFIG` or `I2S_TDM_MSB_SLOT_DEFAULT_CONFIG`
@@ -214,8 +214,8 @@ esp_err_t i2s_channel_init_tdm_mode(i2s_chan_handle_t handle, const i2s_tdm_conf
 /**
  * @brief Reconfigure the I2S clock for TDM mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
- *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to TDM mode, i.e., 'i2s_channel_init_tdm_mode' has been called before reconfiguring
+ *        this function won't change the state. `i2s_channel_disable` should be called before calling this function if I2S has started.
+ * @note  The input channel handle has to be initialized to TDM mode, i.e., `i2s_channel_init_tdm_mode` has been called before reconfiguring
  *
  * @param[in]   handle      I2S channel handler
  * @param[in]   clk_cfg     Standard mode clock configuration, can be generated by `I2S_TDM_CLK_DEFAULT_CONFIG`
@@ -229,8 +229,8 @@ esp_err_t i2s_channel_reconfig_tdm_clock(i2s_chan_handle_t handle, const i2s_tdm
 /**
  * @brief Reconfigure the I2S slot for TDM mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
- *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to TDM mode, i.e., 'i2s_channel_init_tdm_mode' has been called before reconfiguring
+ *        this function won't change the state. `i2s_channel_disable` should be called before calling this function if I2S has started.
+ * @note  The input channel handle has to be initialized to TDM mode, i.e., `i2s_channel_init_tdm_mode` has been called before reconfiguring
  *
  * @param[in]   handle      I2S channel handler
  * @param[in]   slot_cfg    Standard mode slot configuration, can be generated by `I2S_TDM_PHILIPS_SLOT_DEFAULT_CONFIG`,
@@ -244,13 +244,13 @@ esp_err_t i2s_channel_reconfig_tdm_clock(i2s_chan_handle_t handle, const i2s_tdm
 esp_err_t i2s_channel_reconfig_tdm_slot(i2s_chan_handle_t handle, const i2s_tdm_slot_config_t *slot_cfg);
 
 /**
- * @brief Reconfigure the I2S gpio for TDM mode
+ * @brief Reconfigure the I2S GPIO for TDM mode
  * @note  Only allowed to be called when the channel state is READY, i.e., channel has been initialized, but not started
- *        this function won't change the state. 'i2s_channel_disable' should be called before calling this function if i2s has started.
- * @note  The input channel handle has to be initialized to TDM mode, i.e., 'i2s_channel_init_tdm_mode' has been called before reconfiguring
+ *        this function won't change the state. `i2s_channel_disable` should be called before calling this function if I2S has started.
+ * @note  The input channel handle has to be initialized to TDM mode, i.e., `i2s_channel_init_tdm_mode` has been called before reconfiguring
  *
  * @param[in]   handle      I2S channel handler
- * @param[in]   gpio_cfg    Standard mode gpio configuration, specified by user
+ * @param[in]   gpio_cfg    Standard mode GPIO configuration, specified by user
  * @return
  *      - ESP_OK    Set clock successfully
  *      - ESP_ERR_INVALID_ARG   NULL pointer, invalid configuration  or not TDM mode

components/driver/i2s/include/driver/i2s_types.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2020-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -30,7 +30,7 @@ typedef enum {
  * @brief I2S controller communication mode
  */
 typedef enum {
-    I2S_COMM_MODE_STD,              /*!< I2S controller using standard communication mode, support philips/MSB/PCM format */
+    I2S_COMM_MODE_STD,              /*!< I2S controller using standard communication mode, support Philips/MSB/PCM format */
 #if SOC_I2S_SUPPORTS_PDM
     I2S_COMM_MODE_PDM,              /*!< I2S controller using PDM communication mode, support PDM output or input */
 #endif
@@ -41,13 +41,13 @@ typedef enum {
 } i2s_comm_mode_t;
 
 /**
- * @brief The multiple of mclk to sample rate
+ * @brief The multiple of MCLK to sample rate
  */
 typedef enum {
-    I2S_MCLK_MULTIPLE_128       = 128,     /*!< mclk = sample_rate * 128 */
-    I2S_MCLK_MULTIPLE_256       = 256,     /*!< mclk = sample_rate * 256 */
-    I2S_MCLK_MULTIPLE_384       = 384,     /*!< mclk = sample_rate * 384 */
-    I2S_MCLK_MULTIPLE_512       = 512,     /*!< mclk = sample_rate * 512 */
+    I2S_MCLK_MULTIPLE_128       = 128,     /*!< MCLK = sample_rate * 128 */
+    I2S_MCLK_MULTIPLE_256       = 256,     /*!< MCLK = sample_rate * 256 */
+    I2S_MCLK_MULTIPLE_384       = 384,     /*!< MCLK = sample_rate * 384 */
+    I2S_MCLK_MULTIPLE_512       = 512,     /*!< MCLK = sample_rate * 512 */
 } i2s_mclk_multiple_t;
 
 /**
@@ -63,7 +63,7 @@ typedef struct {
                                   */
 } i2s_event_data_t;
 
-typedef struct i2s_channel_obj_t    *i2s_chan_handle_t; /*!< i2s channel object handle, the control unit of the i2s driver*/
+typedef struct i2s_channel_obj_t    *i2s_chan_handle_t; /*!< I2S channel object handle, the control unit of the I2S driver*/
 
 /**
  * @brief I2S event callback

docs/en/api-reference/peripherals/i2s.rst

@@ -252,7 +252,7 @@ Both :cpp:func:`i2s_channel_write` and :cpp:func:`i2s_channel_read` are blocking
 Configuration
 ^^^^^^^^^^^^^
 
-Users can initialize a channel by calling corresponding functions (i.e., :func:`i2s_channel_init_std_mode`, :func:`i2s_channel_init_pdm_rx_mode`, :func:`i2s_channel_init_pdm_tx_mode`, or :func:`i2s_channel_init_tdm_mode`) to a specific mode. If the configurations need to be updated after initialization, users have to first call :cpp:func:`i2s_channel_disable` to ensure that the channel has stopped, and then call corresponding 'reconfig' functions, like :cpp:func:`i2s_channel_reconfig_std_slot`, :cpp:func:`i2s_channel_reconfig_std_clock`, and :cpp:func:`i2s_channel_reconfig_std_gpio`.
+Users can initialize a channel by calling corresponding functions (i.e., :func:`i2s_channel_init_std_mode`, :func:`i2s_channel_init_pdm_rx_mode`, :func:`i2s_channel_init_pdm_tx_mode`, or :func:`i2s_channel_init_tdm_mode`) to a specific mode. If the configurations need to be updated after initialization, users have to first call :cpp:func:`i2s_channel_disable` to ensure that the channel has stopped, and then call corresponding `reconfig` functions, like :cpp:func:`i2s_channel_reconfig_std_slot`, :cpp:func:`i2s_channel_reconfig_std_clock`, and :cpp:func:`i2s_channel_reconfig_std_gpio`.
 
 IRAM Safe
 ^^^^^^^^^
@@ -387,14 +387,14 @@ Here is the table of the real data on the line with different :cpp:member:`i2s_s
 
     i2s_chan_handle_t tx_handle;
     /* Get the default channel configuration by the helper macro.
-     * This helper macro is defined in 'i2s_common.h' and shared by all the I2S communication modes.
+     * This helper macro is defined in `i2s_common.h` and shared by all the I2S communication modes.
      * It can help to specify the I2S role and port ID */
     i2s_chan_config_t chan_cfg = I2S_CHANNEL_DEFAULT_CONFIG(I2S_NUM_AUTO, I2S_ROLE_MASTER);
     /* Allocate a new TX channel and get the handle of this channel */
     i2s_new_channel(&chan_cfg, &tx_handle, NULL);
 
     /* Setting the configurations, the slot configuration and clock configuration can be generated by the macros
-     * These two helper macros are defined in 'i2s_std.h' which can only be used in STD mode.
+     * These two helper macros are defined in `i2s_std.h` which can only be used in STD mode.
      * They can help to specify the slot and clock configurations for initialization or updating */
     i2s_std_config_t std_cfg = {
         .clk_cfg = I2S_STD_CLK_DEFAULT_CONFIG(48000),
@@ -500,14 +500,14 @@ Here is the table of the data received in the buffer with different :cpp:member:
 
     i2s_chan_handle_t rx_handle;
     /* Get the default channel configuration by helper macro.
-     * This helper macro is defined in 'i2s_common.h' and shared by all the I2S communication modes.
+     * This helper macro is defined in `i2s_common.h` and shared by all the I2S communication modes.
      * It can help to specify the I2S role and port ID */
     i2s_chan_config_t chan_cfg = I2S_CHANNEL_DEFAULT_CONFIG(I2S_NUM_AUTO, I2S_ROLE_MASTER);
     /* Allocate a new RX channel and get the handle of this channel */
     i2s_new_channel(&chan_cfg, NULL, &rx_handle);
 
     /* Setting the configurations, the slot configuration and clock configuration can be generated by the macros
-     * These two helper macros are defined in 'i2s_std.h' which can only be used in STD mode.
+     * These two helper macros are defined in `i2s_std.h` which can only be used in STD mode.
      * They can help to specify the slot and clock configurations for initialization or updating */
     i2s_std_config_t std_cfg = {
         .clk_cfg = I2S_STD_CLK_DEFAULT_CONFIG(48000),
@@ -657,7 +657,7 @@ Here is the table of the data received in the buffer with different :cpp:member:
     | 0x0001 | 0x0002 | 0x0003 | 0x0004 | 0x0005 | 0x0006 | 0x0007 | 0x0008 |  ...   |
     +--------+--------+--------+--------+--------+--------+--------+--------+--------+
 
-    Here is the table of the data received in a 'int16_t' buffer with different :cpp:member:`i2s_pdm_rx_slot_config_t::slot_mode` and :cpp:member:`i2s_pdm_rx_slot_config_t::slot_mask`.
+    Here is the table of the data received in a ``int16_t`` buffer with different :cpp:member:`i2s_pdm_rx_slot_config_t::slot_mode` and :cpp:member:`i2s_pdm_rx_slot_config_t::slot_mask`.
 
     .. only:: esp32
 

tools/ci/check_public_headers_exceptions.txt

@@ -22,9 +22,7 @@ components/esp_rom/include/esp32s2/rom/rsa_pss.h
 
 # LWIP: sockets.h uses #include_next<>, which doesn't work correctly with the checker
 # memp_std.h is supposed to be included multiple times with different settings
-components/lwip/lwip/src/include/lwip/priv/memp_std.h
 components/lwip/include/lwip/sockets.h
-components/lwip/lwip/src/include/lwip/prot/nd6.h
 
 ## Header produced non-zero object:
 components/esp_phy/esp32/include/phy_init_data.h
@@ -68,13 +66,9 @@ components/json/cJSON/
 
 components/spiffs/include/spiffs_config.h
 
-components/unity/unity/src/unity_internals.h
-components/unity/unity/extras/
 components/unity/include/unity_config.h
 components/unity/include/unity_test_runner.h
 
-components/cmock/CMock/src/cmock.h
-components/cmock/CMock/src/cmock_internals.h
 
 
 components/openthread/openthread/