Merge branch 'bugfix/doc_changes_v52' into 'release/v5.2'

Use `@file` for file documentation and resolved few doc build warnings(v5.2)

See merge request espressif/esp-idf!28002

components/driver/i2c/include/driver/i2c_types.h

@@ -86,7 +86,7 @@ typedef struct {
  *
  * @param[in]  i2c_slave Handle for I2C slave.
  * @param[out] evt_data I2C capture event data, fed by driver
- * @param[in]  user_ctx User data, set in `i2c_slave_register_event_callbacks()`
+ * @param[in]  arg User data, set in `i2c_slave_register_event_callbacks()`
  *
  * @return Whether a high priority task has been waken up by this function
  */

components/esp_common/include/esp_err.h

@@ -79,7 +79,6 @@ const char *esp_err_to_name_r(esp_err_t code, char *buf, size_t buflen);
 /** @cond */
 void _esp_error_check_failed(esp_err_t rc, const char *file, int line, const char *function, const char *expression) __attribute__((__noreturn__));
 
-/** @cond */
 void _esp_error_check_failed_without_abort(esp_err_t rc, const char *file, int line, const char *function, const char *expression);
 
 #ifndef __ASSERT_FUNC

components/esp_common/src/esp_err_to_name.c

@@ -457,6 +457,9 @@ static const esp_err_msg_t esp_err_msg_table[] = {
 #   endif
 #   ifdef      ESP_ERR_ESPNOW_IF
     ERR_TBL_IT(ESP_ERR_ESPNOW_IF),                              /* 12396 0x306c Interface error */
+#   endif
+#   ifdef      ESP_ERR_ESPNOW_CHAN
+    ERR_TBL_IT(ESP_ERR_ESPNOW_CHAN),                            /* 12397 0x306d Channel error */
 #   endif
     // components/wpa_supplicant/esp_supplicant/include/esp_dpp.h
 #   ifdef      ESP_ERR_DPP_FAILURE

components/esp_wifi/include/esp_now.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2019-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2019-2023 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -41,6 +41,7 @@ extern "C" {
 #define ESP_ERR_ESPNOW_INTERNAL     (ESP_ERR_ESPNOW_BASE + 6) /*!< Internal error */
 #define ESP_ERR_ESPNOW_EXIST        (ESP_ERR_ESPNOW_BASE + 7) /*!< ESPNOW peer has existed */
 #define ESP_ERR_ESPNOW_IF           (ESP_ERR_ESPNOW_BASE + 8) /*!< Interface error */
+#define ESP_ERR_ESPNOW_CHAN         (ESP_ERR_ESPNOW_BASE + 9) /*!< Channel error */
 
 #define ESP_NOW_ETH_ALEN             6         /*!< Length of ESPNOW peer MAC address */
 #define ESP_NOW_KEY_LEN              16        /*!< Length of ESPNOW peer local master key */
@@ -205,7 +206,8 @@ esp_err_t esp_now_unregister_send_cb(void);
   *          - ESP_ERR_ESPNOW_INTERNAL : internal error
   *          - ESP_ERR_ESPNOW_NO_MEM : out of memory, when this happens, you can delay a while before sending the next data
   *          - ESP_ERR_ESPNOW_NOT_FOUND : peer is not found
-  *          - ESP_ERR_ESPNOW_IF : current WiFi interface doesn't match that of peer
+  *          - ESP_ERR_ESPNOW_IF : current Wi-Fi interface doesn't match that of peer
+  *          - ESP_ERR_ESPNOW_CHAN: current Wi-Fi channel doesn't match that of peer
   */
 esp_err_t esp_now_send(const uint8_t *peer_addr, const uint8_t *data, size_t len);
 

components/esp_wifi/include/esp_wifi_crypto_types.h

@@ -134,7 +134,7 @@ typedef int (*esp_sha256_prf_t)(const unsigned char *key, int key_len, const cha
  *
  * @param key Key for HMAC operations
  * @param key_len Length of the key in bytes
- * @param dataPointers to the data area
+ * @param data Pointers to the data area
  * @param data_len Length of the data area
  * @param mac Buffer for the hash (16 bytes)
  * Returns: 0 on success, -1 on failure
@@ -327,7 +327,7 @@ typedef int (*esp_omac1_aes_128_t)(const uint8_t *key, const uint8_t *data, size
  *        Counter Mode Cipher Block Chaining Message Authentication
  *        Code Protocol) which is used in IEEE 802.11i RSN standard.
  * @param tk 128-bit Temporal Key for obtained during 4-way handshake
- * @param hdr Pointer to IEEE802.11 frame headeri needed for AAD
+ * @param ieee80211_hdr Pointer to IEEE802.11 frame headeri needed for AAD
  * @param data Pointer to encrypted data buffer
  * @param data_len Encrypted data length in bytes
  * @param decrypted_len Length of decrypted data
@@ -373,7 +373,7 @@ typedef int (*esp_aes_gmac_t)(const uint8_t *key, size_t keylen, const uint8_t *
  * @param num_elem Number of elements in the data vector
  * @param addr Pointers to the data areas
  * @param len Lengths of the data blocks
- * @param mac Buffer for the hash
+ * @param buf Buffer for the hash
  * Returns: 0 on success, -1 on failure
  */
 typedef int (*esp_sha256_vector_t)(size_t num_elem, const uint8_t *addr[], const size_t *len, uint8_t *buf);

components/esp_wifi/include/esp_wifi_he_types.h

@@ -54,7 +54,8 @@ typedef struct {
                                                  1- acquire the complete HE-LTF2
                                                  2- sample evenly among the HE-LTF1 and HE-LTF2 */
     uint32_t val_scale_cfg : 2;             /**< value 0-3 */
-    uint32_t reserved : 20;                 /**< reserved */
+    uint32_t dump_ack_en : 1;               /**< enable to dump 802.11 ACK frame, default disabled */
+    uint32_t reserved : 19;                 /**< reserved */
 } wifi_csi_acquire_config_t;
 
 /**

components/esp_wifi/include/esp_wifi_types.h

@@ -566,6 +566,7 @@ typedef struct {
     bool channel_filter_en; /**< enable to turn on channel filter to smooth adjacent sub-carrier. Disable it to keep independence of adjacent sub-carrier. Default enabled */
     bool manu_scale;        /**< manually scale the CSI data by left shifting or automatically scale the CSI data. If set true, please set the shift bits. false: automatically. true: manually. Default false */
     uint8_t shift;          /**< manually left shift bits of the scale of the CSI data. The range of the left shift bits is 0~15 */
+    bool dump_ack_en;       /**< enable to dump 802.11 ACK frame, default disabled */
 } wifi_csi_config_t;
 #endif
 
@@ -902,6 +903,7 @@ typedef enum {
     WIFI_EVENT_NDP_INDICATION,           /**< Received NDP Request from a NAN Peer */
     WIFI_EVENT_NDP_CONFIRM,              /**< NDP Confirm Indication */
     WIFI_EVENT_NDP_TERMINATED,           /**< NAN Datapath terminated indication */
+    WIFI_EVENT_HOME_CHANNEL_CHANGE,      /**< WiFi home channel change，doesn't occur when scanning */
 
     WIFI_EVENT_MAX,                      /**< Invalid WiFi event ID */
 } wifi_event_t;
@@ -994,6 +996,14 @@ typedef struct {
     int32_t rssi;                 /**< RSSI value of bss */
 } wifi_event_bss_rssi_low_t;
 
+/** Argument structure for WIFI_EVENT_HOME_CHANNEL_CHANGE event */
+typedef struct {
+    uint8_t            old_chan;   /**< old home channel of the device */
+    wifi_second_chan_t old_snd;    /**< old second channel of the device */
+    uint8_t            new_chan;   /**< new home channel of the device */
+    wifi_second_chan_t new_snd;    /**< new second channel of the device */
+} wifi_event_home_channel_change_t;
+
 /**
   * @brief FTM operation status types
   *

components/protocomm/include/crypto/srp6a/esp_srp.h

@@ -13,6 +13,7 @@ extern "C" {
 #endif
 
 /**
+ * @file esp_srp.h
  * @brief SRP-6a protocol implementation
  *
  * More information on protocol can be found: https://datatracker.ietf.org/doc/html/rfc5054
@@ -98,6 +99,13 @@ typedef enum {
     ESP_NG_3072 = 0,
 } esp_ng_type_t;
 
+/**
+ * @brief esp_srp handle as the result of `esp_srp_init`
+ *
+ * The handle is returned by `esp_srp_init` on successful init. It is then
+ * passed for subsequent API calls as an argument. `esp_srp_free` can be used to
+ * clean up the handle. After `esp_srp_free` the handle becomes invalid.
+ */
 typedef struct esp_srp_handle esp_srp_handle_t;
 
 /**