Merge branch 'feature/esp_docs_1.0.0_v4.4' into 'release/v4.4'

docs: update esp-docs to 1.0.0  (v4.4)

See merge request espressif/esp-idf!18210

.gitlab-ci.yml

@@ -56,7 +56,7 @@ variables:
 
   # Docker images
   BOT_DOCKER_IMAGE_TAG: ":latest"
-  ESP_IDF_DOC_ENV_IMAGE: "$CI_DOCKER_REGISTRY/esp-idf-doc-env:v4.4-1-v5"
+  ESP_IDF_DOC_ENV_IMAGE: "$CI_DOCKER_REGISTRY/esp-idf-doc-env:v4.4-1-v6"
   ESP_ENV_IMAGE: "$CI_DOCKER_REGISTRY/esp-env:v4.4-1"
   AFL_FUZZER_TEST_IMAGE: "$CI_DOCKER_REGISTRY/afl-fuzzer-test:v4.4-1-1"
   CLANG_STATIC_ANALYSIS_IMAGE: "${CI_DOCKER_REGISTRY}/clang-static-analysis:v4.4-1-2"

.gitlab/ci/docs.yml

@@ -58,13 +58,14 @@ check_docs_lang_sync:
 .build_docs_template:
   image: $ESP_IDF_DOC_ENV_IMAGE
   variables:
-    PYTHON_VER: 3.6.13
+    PYTHON_VER: 3.7.10
   tags:
     - build_docs
   dependencies: []
   script:
-    - cd docs
     - pip install -r requirements.txt
+    - cd docs
+    - pip install -U -r requirements.txt
     - build-docs -t $DOCTGT -bs $DOC_BUILDERS -l $DOCLANG build
   parallel:
     matrix:
@@ -74,13 +75,14 @@ check_docs_lang_sync:
 check_docs_gh_links:
   image: $ESP_IDF_DOC_ENV_IMAGE
   variables:
-    PYTHON_VER: 3.6.13
+    PYTHON_VER: 3.7.10
   extends:
     - .pre_check_job_template
     - .doc-rules:build:docs
   script:
-    - cd docs
     - pip install -r requirements.txt
+    - cd docs
+    - pip install -U -r requirements.txt
     - build-docs gh-linkcheck
 
 # stage: build_doc
@@ -150,20 +152,19 @@ build_docs_pdf:
   extends:
     - .before_script_no_sync_submodule
   image: $ESP_IDF_DOC_ENV_IMAGE
-  variables:
-    PYTHON_VER: 3.6.13
   stage: test_deploy
   tags:
     - deploy
     - shiny
   variables:
+    PYTHON_VER: 3.7.10
     DOCS_BUILD_DIR: "${IDF_PATH}/docs/_build/"
     PYTHONUNBUFFERED: 1
   dependencies: []
   script:
     - add_doc_server_ssh_keys $DOCS_DEPLOY_PRIVATEKEY $DOCS_DEPLOY_SERVER $DOCS_DEPLOY_SERVER_USER
     - export GIT_VER=$(git describe --always ${PIPELINE_COMMIT_SHA} --)
-    - pip install -r docs/requirements.txt
+    - pip install -U -r docs/requirements.txt
     - deploy-docs
 
 # stage: test_deploy
@@ -224,7 +225,7 @@ check_doc_links:
     expire_in: 1 week
   allow_failure: true
   script:
-    - cd docs
     - pip install -r requirements.txt
-    # At the moment this check will always fail due to multiple known limitations, ignore result
-    - build-docs -t $DOCTGT -l $DOCLANG linkcheck || { echo "THERE ARE ISSUES DUE TO KNOWN LIMITATIONS, PLEASE FIX THEM. Nowadays we're ignored them to pass pipeline."; true; }
+    - cd docs
+    - pip install -U -r requirements.txt
+    - build-docs -t $DOCTGT -l $DOCLANG linkcheck

components/app_update/include/esp_ota_ops.h

@@ -327,9 +327,9 @@ typedef enum {
 /**
  * @brief Revokes the old signature digest. To be called in the application after the rollback logic.
  *
- * Relevant for Secure boot v2 on ESP32-S2 where upto 3 key digests can be stored (Key #N-1, Key #N, Key #N+1).
- * When key #N-1 used to sign an app is invalidated, an OTA update is to be sent with an app signed with key #N-1 & Key #N.
- * After successfully booting the OTA app should call this function to revoke Key #N-1.
+ * Relevant for Secure boot v2 on ESP32-S2, ESP32-S3, ESP32-C3 where upto 3 key digests can be stored (Key \#N-1, Key \#N, Key \#N+1).
+ * When key \#N-1 used to sign an app is invalidated, an OTA update is to be sent with an app signed with key \#N-1 & Key \#N.
+ * After successfully booting the OTA app should call this function to revoke Key \#N-1.
  *
  * @param index - The index of the signature block to be revoked
  *

components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h

@@ -1455,7 +1455,7 @@ esp_err_t esp_ble_gap_config_local_privacy (bool privacy_enable);
  *
  *
  * @param[in]       icon   - External appearance value, these values are defined by the Bluetooth SIG, please refer to
- *                  https://www.bluetooth.com/specifications/gatt/viewer?attributeXmlFile=org.bluetooth.characteristic.gap.appearance.xml
+ *                  https://specificationrefs.bluetooth.com/assigned-values/Appearance%20Values.pdf
  *
  * @return
  *                  - ESP_OK : success

components/esp_eth/include/esp_eth_mac.h

@@ -411,7 +411,7 @@ typedef struct {
 /**
 * @brief Create ESP32 Ethernet MAC instance
 *
-* @param config: Ethernet MAC configuration
+* @param config:       Ethernet MAC configuration
 *
 * @return
 *      - instance: create MAC instance successfully

components/esp_https_server/include/esp_https_server.h

@@ -25,7 +25,7 @@ typedef enum {
  * @brief Callback data struct, contains the ESP-TLS connection handle
  */
 typedef struct esp_https_server_user_cb_arg {
-    const esp_tls_t *tls;
+    const esp_tls_t *tls;        /*!< ESP-TLS connection handle */
 } esp_https_server_user_cb_arg_t;
 
 /**

components/esp_hw_support/include/esp_mac.h

@@ -139,7 +139,7 @@ esp_err_t esp_read_mac(uint8_t *mac, esp_mac_type_t type);
   * address, then the first octet is XORed with 0x4 in order to create a different
   * locally administered MAC address.
   *
-  * @param  mac base MAC address, length: 6 bytes/8 bytes.
+  * @param  local_mac base MAC address, length: 6 bytes/8 bytes.
   *         length: 6 bytes for MAC-48
   *                 8 bytes for EUI-64(used for IEEE 802.15.4)
   * @param  universal_mac  Source universal MAC address, length: 6 bytes.

components/esp_lcd/include/esp_lcd_panel_io.h

@@ -134,6 +134,10 @@ typedef struct {
  */
 esp_err_t esp_lcd_new_panel_io_spi(esp_lcd_spi_bus_handle_t bus, const esp_lcd_panel_io_spi_config_t *io_config, esp_lcd_panel_io_handle_t *ret_io);
 
+/**
+ * @brief Panel IO configuration structure, for I2C interface
+ *
+ */
 typedef struct {
     uint32_t dev_addr; /*!< I2C device address */
     esp_lcd_panel_io_color_trans_done_cb_t on_color_trans_done; /*!< Callback invoked when color data transfer has finished */
@@ -145,7 +149,7 @@ typedef struct {
     struct {
         unsigned int dc_low_on_data: 1;  /*!< If this flag is enabled, DC line = 0 means transfer data, DC line = 1 means transfer command; vice versa */
         unsigned int disable_control_phase: 1; /*!< If this flag is enabled, the control phase isn't used */
-    } flags;
+    } flags; /*!< Extra flags to fine-tune the I2C device */
 } esp_lcd_panel_io_i2c_config_t;
 
 /**
@@ -223,7 +227,7 @@ typedef struct {
         unsigned int swap_color_bytes: 1;   /*!< Swap adjacent two color bytes */
         unsigned int pclk_active_neg: 1;    /*!< The display will write data lines when there's a falling edge on WR signal (a.k.a the PCLK) */
         unsigned int pclk_idle_low: 1;      /*!< The WR signal (a.k.a the PCLK) stays at low level in IDLE phase */
-    } flags;
+    } flags;                                /*!< Panel IO config flags */
 } esp_lcd_panel_io_i80_config_t;
 
 /**

components/esp_lcd/include/esp_lcd_panel_rgb.h

@@ -66,7 +66,7 @@ typedef struct {
         unsigned int de_idle_high: 1;    /*!< The de signal is high in IDLE state */
         unsigned int pclk_active_neg: 1; /*!< Whether the display data is clocked out at the falling edge of PCLK */
         unsigned int pclk_idle_high: 1;  /*!< The PCLK stays at high level in IDLE phase */
-    } flags;
+    } flags;                             /*!< LCD RGB timing flags */
 } esp_lcd_rgb_timing_t;
 
 /**
@@ -106,7 +106,7 @@ typedef struct {
         unsigned int disp_active_low: 1; /*!< If this flag is enabled, a low level of display control signal can turn the screen on; vice versa */
         unsigned int relax_on_idle: 1;   /*!< If this flag is enabled, the host won't refresh the LCD if nothing changed in host's frame buffer (this is usefull for LCD with built-in GRAM) */
         unsigned int fb_in_psram: 1;     /*!< If this flag is enabled, the frame buffer will be allocated from PSRAM preferentially */
-    } flags;
+    } flags;                             /*!< LCD RGB panel configuration flags */
 } esp_lcd_rgb_panel_config_t;
 
 /**

components/esp_lcd/include/esp_lcd_panel_vendor.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -22,8 +22,8 @@ typedef struct {
     unsigned int bits_per_pixel;       /*!< Color depth, in bpp */
     struct {
         unsigned int reset_active_high: 1; /*!< Setting this if the panel reset is high level active */
-    } flags;
-    void *vendor_config; /* vendor specific configuration, optional, left as NULL if not used */
+    } flags;                               /*!< LCD panel config flags */
+    void *vendor_config; /*!< vendor specific configuration, optional, left as NULL if not used */
 } esp_lcd_panel_dev_config_t;
 
 /**

components/esp_netif/include/esp_netif_ip_addr.h

@@ -81,25 +81,37 @@ extern "C" {
 #define ESP_IP4ADDR_INIT(a, b, c, d)  { .type = ESP_IPADDR_TYPE_V4, .u_addr = { .ip4 = { .addr = ESP_IP4TOADDR(a, b, c, d) }}};
 #define ESP_IP6ADDR_INIT(a, b, c, d)  { .type = ESP_IPADDR_TYPE_V6, .u_addr = { .ip6 = { .addr = { a, b, c, d }, .zone = 0 }}};
 
+/**
+ * @brief IPv6 address
+ *
+ */
 struct esp_ip6_addr {
-    uint32_t addr[4];
-    uint8_t zone;
+    uint32_t addr[4]; /*!< IPv6 address */
+    uint8_t zone;     /*!< zone ID */
 };
 
+/**
+ * @brief IPv4 address
+ *
+ */
 struct esp_ip4_addr {
-    uint32_t addr;
+    uint32_t addr;  /*!< IPv4 address */
 };
 
 typedef struct esp_ip4_addr esp_ip4_addr_t;
 
 typedef struct esp_ip6_addr esp_ip6_addr_t;
 
+/**
+ * @brief IP address
+ *
+ */
 typedef struct _ip_addr {
     union {
-        esp_ip6_addr_t ip6;
-        esp_ip4_addr_t ip4;
-    } u_addr;
-    uint8_t type;
+        esp_ip6_addr_t ip6; /*!< IPv6 address type */
+        esp_ip4_addr_t ip4; /*!< IPv4 address type */
+    } u_addr;               /*!< IP address union */
+    uint8_t type;           /*!< ipaddress type */
 } esp_ip_addr_t;
 
 typedef enum {

components/esp_netif/include/esp_netif_types.h

@@ -112,6 +112,11 @@ typedef struct {
     esp_ip6_addr_t ip; /**< Interface IPV6 address */
 } esp_netif_ip6_info_t;
 
+
+/**
+ * @brief Event structure for IP_EVENT_GOT_IP event
+ *
+ */
 typedef struct {
     int if_index;                    /*!< Interface index for which the event is received (left for legacy compilation) */
     esp_netif_t *esp_netif;          /*!< Pointer to corresponding esp-netif object */
@@ -164,6 +169,10 @@ typedef enum esp_netif_ip_event_type {
 //      3) network stack specific config (esp_netif_net_stack_ifconfig_t) -- no publicly available
 //
 
+/**
+ * @brief ESP-netif inherent config parameters
+ *
+ */
 typedef struct esp_netif_inherent_config {
     esp_netif_flags_t flags;         /*!< flags that define esp-netif behavior */
     uint8_t mac[6];                  /*!< initial mac address for this interface */
@@ -185,19 +194,23 @@ typedef struct esp_netif_config esp_netif_config_t;
  */
 typedef void * esp_netif_iodriver_handle;
 
+/**
+ * @brief ESP-netif driver base handle
+ *
+ */
 typedef struct esp_netif_driver_base_s {
-    esp_err_t (*post_attach)(esp_netif_t *netif, esp_netif_iodriver_handle h);
-    esp_netif_t *netif;
+    esp_err_t (*post_attach)(esp_netif_t *netif, esp_netif_iodriver_handle h); /*!< post attach function pointer */
+    esp_netif_t *netif; /*!< netif handle */
 } esp_netif_driver_base_t;
 
 /**
  * @brief  Specific IO driver configuration
  */
 struct esp_netif_driver_ifconfig {
-    esp_netif_iodriver_handle handle;
-    esp_err_t (*transmit)(void *h, void *buffer, size_t len);
-    esp_err_t (*transmit_wrap)(void *h, void *buffer, size_t len, void *netstack_buffer);
-    void (*driver_free_rx_buffer)(void *h, void* buffer);
+    esp_netif_iodriver_handle handle; /*!< io-driver handle */
+    esp_err_t (*transmit)(void *h, void *buffer, size_t len); /*!< transmit function pointer */
+    esp_err_t (*transmit_wrap)(void *h, void *buffer, size_t len, void *netstack_buffer); /*!< transmit wrap function pointer */
+    void (*driver_free_rx_buffer)(void *h, void* buffer); /*!< free rx buffer function pointer */
 };
 
 typedef struct esp_netif_driver_ifconfig esp_netif_driver_ifconfig_t;
@@ -212,9 +225,9 @@ typedef struct esp_netif_netstack_config esp_netif_netstack_config_t;
  * @brief  Generic esp_netif configuration
  */
 struct esp_netif_config {
-    const esp_netif_inherent_config_t *base;
-    const esp_netif_driver_ifconfig_t *driver;
-    const esp_netif_netstack_config_t *stack;
+    const esp_netif_inherent_config_t *base; /*!< base config */
+    const esp_netif_driver_ifconfig_t *driver; /*!< driver config */
+    const esp_netif_netstack_config_t *stack; /*!< stack config */
 };
 
 /**

components/esp_phy/include/esp_phy_init.h

@@ -14,7 +14,8 @@ extern "C" {
 #endif
 
 /**
- * @file PHY init parameters and API
+ * @file
+ *          init parameters and API
  */
 
 
@@ -34,6 +35,10 @@ typedef struct {
     uint8_t opaque[1894];                   /*!< calibration data */
 } esp_phy_calibration_data_t;
 
+/**
+ * @brief PHY calibration mode
+ *
+ */
 typedef enum {
     PHY_RF_CAL_PARTIAL = 0x00000000,        /*!< Do part of RF calibration. This should be used after power-on reset. */
     PHY_RF_CAL_NONE    = 0x00000001,        /*!< Don't do any RF calibration. This mode is only suggested to be used after deep sleep reset. */
@@ -223,6 +228,10 @@ int64_t esp_phy_rf_get_on_ts(void);
 
 /**
  * @brief Update the corresponding PHY init type according to the country code of Wi-Fi.
+ *
+ * @param country country code
+ * @return ESP_OK on success.
+ * @return esp_err_t code describing the error on fail
  */
 esp_err_t esp_phy_update_country_info(const char *country);
 

components/freertos/include/freertos/queue.h

@@ -1398,9 +1398,6 @@ BaseType_t xQueueGenericSendFromISR( QueueHandle_t xQueue,
                                      const BaseType_t xCopyPosition ) PRIVILEGED_FUNCTION;
 BaseType_t xQueueGiveFromISR( QueueHandle_t xQueue,
                               BaseType_t * const pxHigherPriorityTaskWoken ) PRIVILEGED_FUNCTION;
-/**@}*/
-/** @endcond */
-
 /**
  * @cond !DOC_EXCLUDE_HEADER_SECTION
  * queue. h

components/freertos/include/freertos/task.h

@@ -392,7 +392,7 @@ typedef enum
  * example, to create a privileged task at priority 2 the uxPriority parameter
  * should be set to ( 2 | portPRIVILEGE_BIT ).
  *
- * @param pvCreatedTask Used to pass back a handle by which the created task
+ * @param pxCreatedTask Used to pass back a handle by which the created task
  * can be referenced.
  *
  * @return pdPASS if the task was successfully created and added to a ready
@@ -538,7 +538,7 @@ typedef enum
  *
  * @param uxPriority The priority at which the task will run.
  *
- * @param pxStackBuffer Must point to a StackType_t array that has at least
+ * @param puxStackBuffer Must point to a StackType_t array that has at least
  * ulStackDepth indexes - the array will then be used as the task's stack,
  * removing the need for the stack to be allocated dynamically.
  *
@@ -2368,7 +2368,7 @@ uint32_t ulTaskGetIdleRunTimeCounter( void ) PRIVILEGED_FUNCTION;
  * notification value at that index being updated.  ulValue is not used and
  * xTaskNotifyIndexed() always returns pdPASS in this case.
  *
- * pulPreviousNotificationValue -
+ * @param pulPreviousNotificationValue -
  * Can be used to pass out the subject task's notification value before any
  * bits are modified by the notify function.
  *
@@ -2532,6 +2532,10 @@ BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify,
  * requested from an ISR is dependent on the port - see the documentation page
  * for the port in use.
  *
+ * @param pulPreviousNotificationValue -
+ * Can be used to pass out the subject task's notification value before any
+ * bits are modified by the notify function.
+ *
  * @return Dependent on the value of eAction.  See the description of the
  * eAction parameter.
  *
@@ -2778,11 +2782,10 @@ BaseType_t xTaskGenericNotifyWait( UBaseType_t uxIndexToWaitOn,
  * @endcond
  * \ingroup TaskNotifications
  */
-#define xTaskNotifyGive( xTaskToNotify ) \
-    xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( 0 ), eIncrement, NULL )
 #define xTaskNotifyGiveIndexed( xTaskToNotify, uxIndexToNotify ) \
     xTaskGenericNotify( ( xTaskToNotify ), ( uxIndexToNotify ), ( 0 ), eIncrement, NULL )
-
+#define xTaskNotifyGive( xTaskToNotify ) \
+    xTaskGenericNotify( ( xTaskToNotify ), ( tskDEFAULT_INDEX_TO_NOTIFY ), ( 0 ), eIncrement, NULL )
 /**
  * @cond !DOC_EXCLUDE_HEADER_SECTION
  * task. h

components/hal/include/hal/adc_types.h

@@ -121,7 +121,7 @@ typedef struct {
         struct {
             uint16_t data:     12;  /*!<ADC real output data info. Resolution: 12 bit. */
             uint16_t channel:   4;  /*!<ADC channel index info. */
-        } type1;
+        } type1;                    /*!<ADC type1 */
         struct {
             uint16_t data:     11;  /*!<ADC real output data info. Resolution: 11 bit. */
             uint16_t channel:   4;  /*!<ADC channel index info. For ESP32-S2:

components/protocomm/include/transports/protocomm_ble.h

@@ -79,10 +79,14 @@ typedef struct protocomm_ble_config {
      */
     protocomm_ble_name_uuid_t *nu_lookup;
 
-    /* BLE bonding */
+    /**
+     * BLE bonding
+     */
     unsigned ble_bonding:1;
 
-    /* BLE security flag */
+    /**
+     * BLE security flag
+     */
     unsigned ble_sm_sc:1;
 
 } protocomm_ble_config_t;

components/soc/esp32/include/soc/soc_caps.h

@@ -72,7 +72,6 @@
 /**
  * TO BE REMOVED
  * Check if adc support digital controller (DMA) mode.
- * @value
  *      - 1 : support;
  *      - 0 : not support;
  */

components/touch_element/include/touch_element/touch_element.h

@@ -1,16 +1,8 @@
-// Copyright 2016-2020 Espressif Systems (Shanghai) PTE LTD
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
+/*
+ * SPDX-FileCopyrightText: 2016-2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
 
 #pragma once
 
@@ -180,10 +172,6 @@ esp_err_t touch_element_stop(void);
 /**
  * @brief   Release resources allocated using touch_element_install
  *
- * @return
- *      - ESP_OK: Successfully released touch element object
- *      - ESP_ERR_INVALID_STATE: Touch element object is not initialized
- *      - Others: Unknown touch driver layer or lower layer error
  */
 void touch_element_uninstall(void);
 

components/touch_element/include/touch_element/touch_matrix.h

@@ -1,16 +1,8 @@
-// Copyright 2016-2020 Espressif Systems (Shanghai) PTE LTD
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
+/*
+ * SPDX-FileCopyrightText: 2016-2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
 
 #pragma once
 
@@ -96,8 +88,6 @@ esp_err_t touch_matrix_install(const touch_matrix_global_config_t *global_config
 /**
  * @brief   Release resources allocated using touch_matrix_install()
  *
- * @return
- *      - ESP_OK: Successfully released resources
  */
 void touch_matrix_uninstall(void);
 

components/touch_element/include/touch_element/touch_slider.h

@@ -1,16 +1,8 @@
-// Copyright 2016-2020 Espressif Systems (Shanghai) PTE LTD
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
+/*
+ * SPDX-FileCopyrightText: 2016-2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
 
 #pragma once
 
@@ -98,8 +90,6 @@ esp_err_t touch_slider_install(const touch_slider_global_config_t *global_config
 /**
  * @brief   Release resources allocated using touch_slider_install()
  *
- * @return
- *      - ESP_OK: Successfully released resources
  */
 void touch_slider_uninstall(void);
 

components/usb/include/usb/usb_host.h

@@ -65,10 +65,10 @@ typedef struct {
     union {
         struct {
             uint8_t address;                    /**< New device's address */
-        } new_dev;
+        } new_dev;                              /**< New device info */
         struct {
             usb_device_handle_t dev_hdl;        /**< The handle of the device that was gone */
-        } dev_gone;
+        } dev_gone;                             /**< Gone device info */
     };
 } usb_host_client_event_msg_t;
 
@@ -120,7 +120,7 @@ typedef struct {
         struct {
             usb_host_client_event_cb_t client_event_callback;   /**< Client's event callback function */
             void *callback_arg;                                 /**< Event callback function argument */
-        } async;
+        } async;                                                /**< Async callback config */
     };
 } usb_host_client_config_t;
 

components/usb/include/usb/usb_types_ch9.h

@@ -96,7 +96,7 @@ typedef union {
         uint16_t wIndex;                    /**< Word-sized field that varies according to request; typically used to pass an index or offset */
         uint16_t wLength;                   /**< Number of bytes to transfer if there is a data stage */
     } __attribute__((packed));
-    uint8_t val[USB_SETUP_PACKET_SIZE];
+    uint8_t val[USB_SETUP_PACKET_SIZE];     /**< Descriptor value */
 } usb_setup_packet_t;
 _Static_assert(sizeof(usb_setup_packet_t) == USB_SETUP_PACKET_SIZE, "Size of usb_setup_packet_t incorrect");
 
@@ -241,8 +241,8 @@ typedef union {
     struct {
         uint8_t bLength;                    /**< Size of the descriptor in bytes */
         uint8_t bDescriptorType;            /**< Descriptor Type */
-    } USB_DESC_ATTR;
-    uint8_t val[USB_STANDARD_DESC_SIZE];
+    } USB_DESC_ATTR;                        /**< USB descriptor attributes */
+    uint8_t val[USB_STANDARD_DESC_SIZE];    /**< Descriptor value */
 } usb_standard_desc_t;
 _Static_assert(sizeof(usb_standard_desc_t) == USB_STANDARD_DESC_SIZE, "Size of usb_standard_desc_t incorrect");
 
@@ -274,8 +274,8 @@ typedef union {
         uint8_t iProduct;                   /**< Index of string descriptor describing product */
         uint8_t iSerialNumber;              /**< Index of string descriptor describing the device’s serial number */
         uint8_t bNumConfigurations;         /**< Number of possible configurations */
-    } USB_DESC_ATTR;
-    uint8_t val[USB_DEVICE_DESC_SIZE];
+    } USB_DESC_ATTR;                        /**< USB descriptor attributes */
+    uint8_t val[USB_DEVICE_DESC_SIZE];      /**< Descriptor value */
 } usb_device_desc_t;
 _Static_assert(sizeof(usb_device_desc_t) == USB_DEVICE_DESC_SIZE, "Size of usb_device_desc_t incorrect");
 
@@ -337,8 +337,8 @@ typedef union {
         uint8_t iConfiguration;             /**< Index of string descriptor describing this configuration */
         uint8_t bmAttributes;               /**< Configuration characteristics */
         uint8_t bMaxPower;                  /**< Maximum power consumption of the USB device from the bus in this specific configuration when the device is fully operational. */
-    } USB_DESC_ATTR;
-    uint8_t val[USB_CONFIG_DESC_SIZE];
+    } USB_DESC_ATTR;                        /**< USB descriptor attributes */
+    uint8_t val[USB_CONFIG_DESC_SIZE];      /**< Descriptor value */
 } usb_config_desc_t;
 _Static_assert(sizeof(usb_config_desc_t) == USB_CONFIG_DESC_SIZE, "Size of usb_config_desc_t incorrect");
 
@@ -370,8 +370,8 @@ typedef union {
         uint8_t bFunctionSubClass;          /**< Subclass code (assigned by USB-IF) */
         uint8_t bFunctionProtocol;          /**< Protocol code (assigned by USB-IF) */
         uint8_t iFunction;                  /**< Index of string descriptor describing this function */
-    } USB_DESC_ATTR;
-    uint8_t val[USB_IAD_DESC_SIZE];
+    } USB_DESC_ATTR;                        /**< USB descriptor attributes */
+    uint8_t val[USB_IAD_DESC_SIZE];         /**< Descriptor value */
 } usb_iad_desc_t;
 _Static_assert(sizeof(usb_iad_desc_t) == USB_IAD_DESC_SIZE, "Size of usb_iad_desc_t incorrect");
 
@@ -398,8 +398,8 @@ typedef union {
         uint8_t bInterfaceSubClass;         /**< Subclass code (assigned by the USB-IF) */
         uint8_t bInterfaceProtocol;         /**< Protocol code (assigned by the USB) */
         uint8_t iInterface;                 /**< Index of string descriptor describing this interface */
-    } USB_DESC_ATTR;
-    uint8_t val[USB_INTF_DESC_SIZE];
+    } USB_DESC_ATTR;                        /**< USB descriptor attributes */
+    uint8_t val[USB_INTF_DESC_SIZE];        /**< Descriptor value */
 } usb_intf_desc_t;
 _Static_assert(sizeof(usb_intf_desc_t) == USB_INTF_DESC_SIZE, "Size of usb_intf_desc_t incorrect");
 
@@ -423,8 +423,8 @@ typedef union {
         uint8_t bmAttributes;               /**< This field describes the endpoint’s attributes when it is configured using the bConfigurationValue. */
         uint16_t wMaxPacketSize;            /**< Maximum packet size this endpoint is capable of sending or receiving when this configuration is selected. */
         uint8_t bInterval;                  /**< Interval for polling Isochronous and Interrupt endpoints. Expressed in frames or microframes depending on the device operating speed (1 ms for Low-Speed and Full-Speed or 125 us for USB High-Speed and above). */
-    } USB_DESC_ATTR;
-    uint8_t val[USB_EP_DESC_SIZE];
+    } USB_DESC_ATTR;                        /**< USB descriptor attributes */
+    uint8_t val[USB_EP_DESC_SIZE];          /**< Descriptor value */
 } usb_ep_desc_t;
 _Static_assert(sizeof(usb_ep_desc_t) == USB_EP_DESC_SIZE, "Size of usb_ep_desc_t incorrect");
 
@@ -475,8 +475,8 @@ typedef union {
         uint8_t bLength;                    /**< Size of the descriptor in bytes */
         uint8_t bDescriptorType;            /**< STRING Descriptor Type */
         uint16_t wData[];                   /**< UTF-16LE encoded */
-    } USB_DESC_ATTR;
-    uint8_t val[USB_STR_DESC_SIZE];
+    } USB_DESC_ATTR;                        /**< USB descriptor attributes */
+    uint8_t val[USB_STR_DESC_SIZE];         /**< Descriptor value */
 } usb_str_desc_t;
 _Static_assert(sizeof(usb_str_desc_t) == USB_STR_DESC_SIZE, "Size of usb_str_desc_t incorrect");
 

components/usb/include/usb/usb_types_stack.h

@@ -122,6 +122,10 @@ typedef struct usb_transfer_s usb_transfer_t;
  */
 typedef void (*usb_transfer_cb_t)(usb_transfer_t *transfer);
 
+/**
+ * @brief USB transfer structure
+ *
+ */
 struct usb_transfer_s{
     uint8_t *const data_buffer;                     /**< Pointer to data buffer */
     const size_t data_buffer_size;                  /**< Size of the data buffer in bytes */

docs/conf_common.py

@@ -12,6 +12,7 @@
 from __future__ import print_function, unicode_literals
 
 import os.path
+import re
 
 from esp_docs.conf_docs import *  # noqa: F403,F401
 
@@ -172,6 +173,19 @@ google_analytics_id = os.environ.get('CI_GOOGLE_ANALYTICS_ID', None)
 
 project_homepage = 'https://github.com/espressif/esp-idf'
 
+linkcheck_anchors = False
+
+linkcheck_exclude_documents = ['index',  # several false positives due to the way we link to different sections
+                               'api-reference/protocols/esp_local_ctrl',  # Fails due to `https://<mdns-hostname>.local`
+                               'api-reference/provisioning/wifi_provisioning',  # Fails due to `https://<mdns-hostname>.local`
+                               ]
+
+
+linkcheck_ignore = ['https://webhome.phy.duke.edu/~rgb/General/dieharder.php',  # Certificate error
+                    'https://dl.espressif.com/dl/esp32s3_rom.elf',  # Not published
+                    ]
+
+
 # Custom added feature to allow redirecting old URLs
 with open('../page_redirects.txt') as f:
     lines = [re.sub(' +', ' ', line.strip()) for line in f.readlines() if line.strip() != '' and not line.startswith('#')]

docs/doxygen-known-warnings.txt

@@ -1 +1,3 @@
 semphr.h:line: warning: argument 'pxStaticSemaphore' of command @param is not found in the argument list of xSemaphoreCreateCounting(uxMaxCount, uxInitialCount)
+task.h:line: warning: argument 'pxTaskDefinition' of command @param is not found in the argument list of vTaskAllocateMPURegions(TaskHandle_t xTask, const MemoryRegion_t *const pxRegions)
+task.h:line: warning: argument 'pxCreatedTask' of command @param is not found in the argument list of vTaskAllocateMPURegions(TaskHandle_t xTask, const MemoryRegion_t *const pxRegions)

docs/doxygen/Doxyfile

@@ -183,7 +183,6 @@ INPUT = \
     $(PROJECT_PATH)/components/esp_system/include/esp_task_wdt.h \
     $(PROJECT_PATH)/components/esp_hw_support/include/esp_crc.h \
     $(PROJECT_PATH)/components/esp_system/include/esp_freertos_hooks.h \
-    $(PROJECT_PATH)/components/esp_ipc/include/esp_ipc.h \
     $(PROJECT_PATH)/components/esp_system/include/esp_expression_with_stack.h \
     $(PROJECT_PATH)/components/app_update/include/esp_ota_ops.h \
     $(PROJECT_PATH)/components/esp_https_ota/include/esp_https_ota.h \
@@ -200,8 +199,6 @@ INPUT = \
     $(PROJECT_PATH)/components/esp_pm/include/esp_pm.h \
     $(PROJECT_PATH)/components/esp_pm/include/$(IDF_TARGET)/pm.h \
     $(PROJECT_PATH)/components/esp_timer/include/esp_timer.h \
-    $(PROJECT_PATH)/components/esp_event/include/esp_event.h \
-    $(PROJECT_PATH)/components/esp_event/include/esp_event_base.h \
     $(PROJECT_PATH)/components/efuse/include/esp_efuse.h \
     $(PROJECT_PATH)/components/bootloader_support/include/esp_app_format.h \
     $(PROJECT_PATH)/components/pthread/include/esp_pthread.h \
@@ -215,7 +212,6 @@ INPUT = \
     $(PROJECT_PATH)/components/esp_ringbuf/include/freertos/ringbuf.h \
     $(PROJECT_PATH)/components/esp_common/include/esp_err.h \
     $(PROJECT_PATH)/components/esp_common/include/esp_check.h \
-    $(PROJECT_PATH)/components/esp_system/include/esp_system.h \
     $(PROJECT_PATH)/components/freemodbus/common/include/esp_modbus_common.h \
     $(PROJECT_PATH)/components/freemodbus/common/include/esp_modbus_slave.h \
     $(PROJECT_PATH)/components/freemodbus/common/include/esp_modbus_master.h \
@@ -237,7 +233,7 @@ WARN_NO_PARAMDOC = YES
 ##
 ENABLE_PREPROCESSING   = YES
 MACRO_EXPANSION        = YES
-EXPAND_ONLY_PREDEF     = YES
+EXPAND_ONLY_PREDEF     = NO
 PREDEFINED             = \
     $(ENV_DOXYGEN_DEFINES) \
     __DOXYGEN__=1 \
@@ -253,6 +249,8 @@ PREDEFINED             = \
     configNUM_THREAD_LOCAL_STORAGE_POINTERS=1 \
     configUSE_APPLICATION_TASK_TAG=1 \
     configTASKLIST_INCLUDE_COREID=1 \
+    portUSING_MPU_WRAPPERS=1 \
+    PRIVILEGED_FUNCTION= \
     "ESP_EVENT_DECLARE_BASE(x)=extern esp_event_base_t x"
 
 ## Do not complain about not having dot
@@ -276,6 +274,5 @@ QUIET = YES
 
 ## Enable Section Tags for conditional documentation
 ##
-ENABLED_SECTIONS += \
-    DOC_EXCLUDE_HEADER_SECTION \   ## To conditionally remove doc sections from IDF source files without affecting documentation in upstream files.
-    DOC_SINGLE_GROUP        ## To conditionally remove groups from the documentation and create a 'flat' document without affecting documentation in upstream files.
+ENABLED_SECTIONS += DOC_EXCLUDE_HEADER_SECTION  ## To conditionally remove doc sections from IDF source files without affecting documentation in upstream files.
+ENABLED_SECTIONS += DOC_SINGLE_GROUP            ## To conditionally remove groups from the documentation and create a 'flat' document without affecting documentation in upstream files.

docs/doxygen/Doxyfile_esp32s3

@@ -9,7 +9,6 @@ INPUT += \
          $(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/touch_sensor_channel.h \
          $(PROJECT_PATH)/components/driver/$(IDF_TARGET)/include/driver/touch_sensor.h \
          $(PROJECT_PATH)/components/ulp/include/esp32s3/ulp_riscv.h \
-         $(PROJECT_PATH)/components/ulp/include/$(IDF_TARGET)/ulp.h \
          $(PROJECT_PATH)/components/usb/include/usb/usb_helpers.h \
          $(PROJECT_PATH)/components/usb/include/usb/usb_host.h \
          $(PROJECT_PATH)/components/usb/include/usb/usb_types_ch9.h \

docs/en/api-guides/esp-ble-mesh/ble-mesh-faq.rst

@@ -527,11 +527,13 @@ Generally, a Provisioner is used to provision unprovisioned devices and form a m
 3.2 Why is the Wi-Fi throughput so low when Wi-Fi and ESP-BLE-MESH coexist?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-    The `ESP32-DevKitC <../../hw-reference/esp32/get-started-devkitc>`_ board without PSRAM can run properly but the throughput of it is low since it has no PSRAM. When Bluetooth and Wi-Fi coexist, the throughput of ESP32-DevKitC with PSRAM can be stabilized to more than 1Mbps.
+    .. only:: esp32
 
-    And some configurations in menuconfig shall be enabled to support PSRAM.
+        The :doc:`ESP32-DevKitC <../../hw-reference/esp32/get-started-devkitc>` board without PSRAM can run properly but the throughput of it is low since it has no PSRAM. When Bluetooth and Wi-Fi coexist, the throughput of ESP32-DevKitC with PSRAM can be stabilized to more than 1Mbps.
 
-        - :code:`ESP32-specific --> Support for external,SPI-connected RAM --> Try to allocate memories of Wi-Fi and LWIP...`
+    Some configurations in menuconfig shall be enabled to support PSRAM.
+
+        - :code:`{IDF_TARGET_NAME}-specific --> Support for external,SPI-connected RAM --> Try to allocate memories of Wi-Fi and LWIP...`
         - :code:`Bluetooth --> Bluedroid Enable --> BT/BLE will first malloc the memory from the PSRAM`
         - :code:`Bluetooth --> Bluedroid Enable --> Use dynamic memory allocation in BT/BLE stack.`
         - :code:`Bluetooth --> Bluetooth controller --> BLE full scan feature supported.`

docs/en/api-reference/api-conventions.rst

@@ -9,7 +9,7 @@ ESP-IDF provides several kinds of programming interfaces:
 
 * C functions, structures, enums, type definitions and preprocessor macros declared in public header files of ESP-IDF components. Various pages in the API Reference section of the programming guide contain descriptions of these functions, structures and types.
 * Build system functions, predefined variables and options. These are documented in the :ref:`build system guide<cmake_buildsystem_api>`.
-* `Kconfig <kconfig>`_ options can can be used in code and in the build system (CMakeLists.txt) files.
+* :doc:`Kconfig <kconfig>` options can can be used in code and in the build system (CMakeLists.txt) files.
 * :doc:`Host tools <../api-guides/tools/index>` and their command line parameters are also part of ESP-IDF interface.
 
 ESP-IDF consists of components written specifically for ESP-IDF as well as third-party libraries. In some cases, an ESP-IDF-specific wrapper is added to the third-party library, providing an interface that is either simpler or better integrated with the rest of ESP-IDF facilities. In other cases, the original API of the third-party library is presented to the application developers.
@@ -96,7 +96,7 @@ It is not recommended to reference these components directly in custom projects
 API Stability
 -------------
 
-ESP-IDF uses `Semantic Versioning <http://semver.org/>`_ as explained in the :ref:`versions page<versioning-scheme>`.
+ESP-IDF uses `Semantic Versioning <https://semver.org/>`_ as explained in the :ref:`versions page<versioning-scheme>`.
 
 Minor and bugfix releases of ESP-IDF guarantee compatibility with previous releases. The sections below explain different aspects and limitations to compatibility.
 
@@ -109,7 +109,7 @@ The following changes are allowed between minor versions and do not break source
 
 * Deprecating functions (using the ``deprecated`` attribute) and header files (using a preprocessor ``#warning``). Deprecations are listed in ESP-IDF relese notes. It is recommended to update the source code to use the newer functions or files that replace the deprecated ones, however this is not mandatory. Deprecated functions and files can be removed in major versions of ESP-IDF.
 * Renaming components, moving source and header files between components — provided that the build system ensures that correct files are still found.
-* Renaming Kconfig options. Kconfig system `renaming mechanism <configuration-options-compatibility>`_ ensures that the original Kconfig option names can still be used by the application in ``sdkconfig`` file, CMake files and source code.
+* Renaming Kconfig options. Kconfig system :ref:`renaming mechanism <configuration-options-compatibility>` ensures that the original Kconfig option names can still be used by the application in ``sdkconfig`` file, CMake files and source code.
 
 Lack of binary compatibility
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -132,7 +132,7 @@ While we try to make upgrading to a new ESP-IDF version easy, there are parts of
 * Changes made to mitigate security issues or to replace insecure default behaviors with a secure ones.
 * Features which were never functional. For example, if it was never possible to use a certain function or an enumeration value, it may get renamed (as part of fixing it) or removed. This includes software features which depend on non-functional chip hardware features.
 * Unexpected or undefined behavior (for example, due to missing validation of argument ranges) that is not documented explicitly may be fixed/changed.
-* Location of `Kconfig <kconfig>`_ options in menuconfig.
+* Location of :doc:`Kconfig <kconfig>` options in menuconfig.
 * Location and names of example projects.
 
 .. _designated initializers: https://en.cppreference.com/w/c/language/struct_initialization

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

@@ -28,14 +28,17 @@ For other analog output options, see the :doc:`Sigma-delta Modulation module <si
 Application Example
 -------------------
 
-Setting DAC channel 1 ({IDF_TARGET_DAC_CH_1}) voltage to approx 0.78 of VDD_A voltage (VDD * 200 / 255). For VDD_A 3.3V, this is 2.59V::
+Setting DAC channel 1 ({IDF_TARGET_DAC_CH_1}) voltage to approx 0.78 of VDD_A voltage (VDD * 200 / 255). For VDD_A 3.3V, this is 2.59V.
 
-  #include <driver/dac.h>
+.. code:: c
 
-  ...
+    #include <driver/dac.h>
+
+    ...
+
+    dac_output_enable(DAC_CHANNEL_1);
+    dac_output_voltage(DAC_CHANNEL_1, 200);
 
-      dac_output_enable(DAC_CHANNEL_1);
-      dac_output_voltage(DAC_CHANNEL_1, 200);
 
 API Reference
 -------------

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

@@ -25,7 +25,7 @@ In-depth design details of touch sensors and firmware development guidelines for
 
 .. only:: SOC_TOUCH_VERSION_1
 
-    For more information about testing touch sensors in various configurations, please check the `Guide for ESP32-Sense-Kit <https://github.com/espressif/esp-dev-kits/blob/master/esp32-sense-kit/docs/esp32_sense_kit_guide_en.md>`_.
+    For more information about testing touch sensors in various configurations, please check the `Guide for ESP32-Sense-Kit <https://docs.espressif.com/projects/espressif-esp-dev-kits/en/latest/esp32/esp32-sense-kit/user_guide.html>`_.
 
 Functionality Overview
 ----------------------

docs/en/api-reference/system/mem_alloc.rst

@@ -151,12 +151,14 @@ Implementation Notes
 
 Knowledge about the regions of memory in the chip comes from the "soc" component, which contains memory layout information for the chip, and the different capabilities of each region. Each region's capabilities are prioritised, so that (for example) dedicated DRAM and IRAM regions will be used for allocations ahead of the more versatile D/IRAM regions.
 
-Each contiguous region of memory contains its own memory heap. The heaps are created using the `multi_heap <API Reference - Multi Heap API>`_ functionality. multi_heap allows any contiguous region of memory to be used as a heap.
+Each contiguous region of memory contains its own memory heap. The heaps are created using the :ref:`multi_heap <multi-heap>` functionality. multi_heap allows any contiguous region of memory to be used as a heap.
 
 The heap capabilities allocator uses knowledge of the memory regions to initialize each individual heap. Allocation functions in the heap capabilities API will find the most appropriate heap for the allocation (based on desired capabilities, available space, and preferences for each region's use) and then calling :cpp:func:`multi_heap_malloc` or :cpp:func:`multi_heap_calloc` for the heap situated in that particular region.
 
 Calling ``free()`` involves finding the particular heap corresponding to the freed address, and then calling :cpp:func:`multi_heap_free` on that particular multi_heap instance.
 
+.. _multi-heap:
+
 API Reference - Multi Heap API
 ------------------------------
 

docs/requirements.txt

@@ -1 +1 @@
-esp-docs==0.1.1
+esp-docs~=1.1.0

docs/sphinx-known-warnings.txt

@@ -6,76 +6,60 @@
 #
 # Warnings in this file must be in the same overall order as the log file.
 #
-#
-# Breathe known issue: https://github.com/michaeljones/breathe/issues/405
-# Sphinx known issue: https://github.com/sphinx-doc/sphinx/pull/5901
-#
-# Note: warnings below have been identified after upgrade
-#       to the following package==version
-#
-#       sphinx==1.8.4
-#       breathe==4.11.1
-#
-ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_load_binary(uint32_t load_addr, const uint8_t * program_binary, size_t program_size)
-ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point)
-ulp.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us)
-ulp-legacy.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_load_binary(uint32_t load_addr, const uint8_t * program_binary, size_t program_size)
-ulp-legacy.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point)
-ulp-legacy.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us)
-ulp-risc-v.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_set_wakeup_period(size_t period_index, uint32_t period_us)
-README.rst:line: WARNING: Duplicate declaration, esp_err_t ulp_run(uint32_t entry_point)
-
-
-# This seems like a bug, as the field are ::model_id and ::vnd::model_id
-esp_ble_mesh_defs.inc:line: WARNING: Duplicate declaration, uint16_t esp_ble_mesh_model::model_id
-WARNING:esp_bt_defs, use :noindex: for one of them
-WARNING:esp_blufi, use :noindex: for one of them
-esp_bt_defs.inc:line: WARNING: Duplicate declaration, uint8_t esp_bd_addr_t[ESP_BD_ADDR_LEN]
-
-#
-# Issue present only when building on msys2 / mingw32 START >>>
-#
+ulp-legacy.rst:line: WARNING: Duplicate C++ declaration, also defined at api-guides/ulp:line.
+Declaration is '.. cpp:function:: esp_err_t ulp_load_binary (uint32_t load_addr, const uint8_t *program_binary, size_t program_size)'.
+ulp-legacy.rst:line: WARNING: Duplicate C++ declaration, also defined at api-guides/ulp:line.
+Declaration is '.. cpp:function:: esp_err_t ulp_run (uint32_t entry_point)'.
+ulp-legacy.rst:line: WARNING: Duplicate C++ declaration, also defined at api-guides/ulp:line.
+Declaration is '.. cpp:function:: esp_err_t ulp_set_wakeup_period (size_t period_index, uint32_t period_us)'.
+README.rst:line: WARNING: Duplicate C++ declaration, also defined at api-guides/ulp:line.
+Declaration is '.. cpp:function:: esp_err_t ulp_run (uint32_t entry_point)'.
+esp_ble_mesh_defs.inc:line: WARNING: Duplicate C++ declaration, also defined at api-reference/bluetooth/esp-ble-mesh:line.
+Declaration is '.. cpp:member:: uint16_t model_id'.
+esp_bt_defs.inc:line: WARNING: Duplicate C declaration, also defined at api-reference/bluetooth/esp_blufi:line.
+Declaration is '.. c:macro:: ESP_BD_ADDR_LEN'.
+esp_bt_defs.inc:line: WARNING: Duplicate C++ declaration, also defined at api-reference/bluetooth/esp_blufi:line.
+Declaration is '.. cpp:type:: uint8_t esp_bd_addr_t [6]'.
 esp_spp_api.inc:line: WARNING: Error in type declaration.
 If typedef-like declaration:
   Type must be either just a name or a typedef-like declaration.
   If just a name:
-    Error in declarator or parameters and qualifiers
-    Invalid definition: Expected identifier in nested name, got keyword: void [error at 4]
-      void() esp_spp_cb_t(esp_spp_cb_event_t event, esp_spp_cb_param_t *param)
+    Error in declarator or parameters-and-qualifiers
+    Invalid C++ declaration: Expected identifier in nested name, got keyword: void [error at 4]
+      void() esp_spp_cb_t (esp_spp_cb_event_t event, esp_spp_cb_param_t *param)
       ----^
   If typedef-like declaration:
     Error in declarator
-    If pointer to member declarator:
-      Invalid definition: Expected identifier in nested name. [error at 4]
-        void() esp_spp_cb_t(esp_spp_cb_event_t event, esp_spp_cb_param_t *param)
-        ----^
-    If declId, parameters, and qualifiers:
-      Invalid definition: Expected identifier in nested name. [error at 4]
-        void() esp_spp_cb_t(esp_spp_cb_event_t event, esp_spp_cb_param_t *param)
+    If declarator-id with parameters-and-qualifiers:
+      Invalid C++ declaration: Expected identifier in nested name. [error at 4]
+        void() esp_spp_cb_t (esp_spp_cb_event_t event, esp_spp_cb_param_t *param)
         ----^
     If parenthesis in noptr-declarator:
-      Error in declarator or parameters and qualifiers
+      Error in declarator or parameters-and-qualifiers
       If pointer to member declarator:
-        Invalid definition: Expected identifier in nested name. [error at 5]
-          void() esp_spp_cb_t(esp_spp_cb_event_t event, esp_spp_cb_param_t *param)
+        Invalid C++ declaration: Expected identifier in nested name. [error at 5]
+          void() esp_spp_cb_t (esp_spp_cb_event_t event, esp_spp_cb_param_t *param)
           -----^
       If declarator-id:
-        Invalid definition: Expected identifier in nested name. [error at 5]
-          void() esp_spp_cb_t(esp_spp_cb_event_t event, esp_spp_cb_param_t *param)
+        Invalid C++ declaration: Expected identifier in nested name. [error at 5]
+          void() esp_spp_cb_t (esp_spp_cb_event_t event, esp_spp_cb_param_t *param)
           -----^
 If type alias or template alias:
-  Invalid definition: Expected identifier in nested name, got keyword: void [error at 4]
-    void() esp_spp_cb_t(esp_spp_cb_event_t event, esp_spp_cb_param_t *param)
+  Invalid C++ declaration: Expected identifier in nested name, got keyword: void [error at 4]
+    void() esp_spp_cb_t (esp_spp_cb_event_t event, esp_spp_cb_param_t *param)
     ----^
 
-#
-# Issue present only when building on msys2 / mingw32 END <<<
-#
-spi_master.inc:line: WARNING: Duplicate declaration, struct spi_transaction_t spi_transaction_t
-spi_slave.inc:line: WARNING: Duplicate declaration, struct spi_slave_transaction_t spi_slave_transaction_t
-esp_flash.inc:line: WARNING: Duplicate declaration, struct esp_flash_t esp_flash_t
-spi_flash_types.inc:line: WARNING: Duplicate declaration, struct spi_flash_host_driver_t spi_flash_host_driver_t
-wear-levelling.rst:line: WARNING: Duplicate declaration, bool esp_vfs_fat_mount_config_t::format_if_mount_failed
-wear-levelling.rst:line: WARNING: Duplicate declaration, int esp_vfs_fat_mount_config_t::max_files
-wear-levelling.rst:line: WARNING: Duplicate declaration, size_t esp_vfs_fat_mount_config_t::allocation_unit_size
-wear-levelling.rst:line: WARNING: Duplicate declaration, esp_vfs_fat_mount_config_t
+spi_master.inc:line: WARNING: Duplicate C++ declaration, also defined at api-reference/peripherals/spi_master:line.
+Declaration is '.. cpp:type:: struct spi_transaction_t spi_transaction_t'.
+spi_slave.inc:line: WARNING: Duplicate C++ declaration, also defined at api-reference/peripherals/spi_slave:line.
+Declaration is '.. cpp:type:: struct spi_slave_transaction_t spi_slave_transaction_t'.
+esp_flash.inc:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/spi_flash:line.
+Declaration is '.. cpp:type:: struct esp_flash_t esp_flash_t'.
+wear-levelling.rst:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/fatfs:line.
+Declaration is '.. cpp:struct:: esp_vfs_fat_mount_config_t'.
+wear-levelling.rst:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/fatfs:line.
+Declaration is '.. cpp:member:: bool format_if_mount_failed'.
+wear-levelling.rst:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/fatfs:line.
+Declaration is '.. cpp:member:: int max_files'.
+wear-levelling.rst:line: WARNING: Duplicate C++ declaration, also defined at api-reference/storage/fatfs:line.
+Declaration is '.. cpp:member:: size_t allocation_unit_size'.

docs/zh_CN/api-guides/build-system.rst

@@ -1136,7 +1136,7 @@ CMake 在许多开源的 C/C++ 项目中广泛使用，用户可以在自己的
 
 实际的案例请参考 :example:`build_system/cmake/import_lib`。请注意，导入第三方库所需要做的工作可能会因库的不同而有所差异。建议仔细阅读第三方库的文档，了解如何将其导入到其它项目中。阅读第三方库的 CMakeLists.txt 文件以及构建结构也会有所帮助。
 
-用这种方式还可以将第三方库封装成 ESP-IDF 的组件。例如 :component:`mbedtls` 组件就是封装了 `mbedtls 项目 <https://github.com/ARMmbed/mbedtls>`_ 得到的。详情请参考 :component_file:`mbedtls 组件的 CMakeLists.txt 文件 <mbedtls/CMakeLists.txt>`。
+用这种方式还可以将第三方库封装成 ESP-IDF 的组件。例如 :component:`mbedtls` 组件就是封装了 `mbedtls 项目 <https://github.com/Mbed-TLS/mbedtls>`_ 得到的。详情请参考 :component_file:`mbedtls 组件的 CMakeLists.txt 文件 <mbedtls/CMakeLists.txt>`。
 
 每当使用 ESP-IDF 构建系统时，CMake 变量 ``ESP_PLATFORM`` 都会被设置为 1。如果要在通用的 CMake 代码加入 IDF 特定的代码时，可以采用 ``if (ESP_PLATFORM)`` 的形式加以分隔。
 
@@ -1582,7 +1582,7 @@ CMake 中不可用的功能
 - ``COMPONENT_OBJS``：以前，可以以目标文件列表的方式指定组件源，现在，可以通过 ``COMPONENT_SRCS`` 以源文件列表的形式指定组件源。
 - ``COMPONENT_OBJEXCLUDE``：已被 ``COMPONENT_SRCEXCLUDE`` 替换。用于指定源文件（绝对路径或组件目录的相对路径）。
 - ``COMPONENT_EXTRA_CLEAN``：已被 ``ADDITIONAL_MAKE_CLEAN_FILES`` 属性取代，注意，:ref:`CMake 对此项功能有部分限制 <ADDITIONAL_MAKE_CLEAN_FILES_note>`。
-- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``：已被 CMake `外部项目 <ExternalProject>`_ 替代，详细内容请参阅 :ref:`component-build-full-override`。
+- ``COMPONENT_OWNBUILDTARGET`` & ``COMPONENT_OWNCLEANTARGET``：已被 CMake `外部项目 <ExternalProject_>` 替代，详细内容请参阅 :ref:`component-build-full-override`。
 - ``COMPONENT_CONFIG_ONLY``：已被 ``register_config_only_component()`` 函数替代，请参阅 :ref:`config_only_component`。
 - ``CFLAGS``、``CPPFLAGS``、``CXXFLAGS``：已被相应的 CMake 命令替代，请参阅 :ref:`component_build_control`。
 

docs/zh_CN/api-guides/esp-ble-mesh/ble-mesh-faq.rst

@@ -530,11 +530,13 @@ ESP-BLE-MESH 常见问题手册
 3.2 Wi-Fi 和 ESP-BLE-MESH 共存时，为什么 Wi-Fi 吞吐量很低？
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-    未搭载 PSRAM 的 `ESP32-DevKitC <../../hw-reference/get-started-devkitc>`_ 开发板，Wi-Fi 和 ESP-BLE-MESH 共存可以正常运行，但是吞吐率较低。当 Wi-Fi 和 ESP-BLE-MESH 共存时，搭载 PSRAM 的 ESP32-DevKitC 速率可以稳定在 1 Mbps 以上。
+    .. only:: esp32
+
+        未搭载 PSRAM 的 :doc:`ESP32-DevKitC <../../hw-reference/esp32/get-started-devkitc>` 开发板，Wi-Fi 和 ESP-BLE-MESH 共存可以正常运行，但是吞吐率较低。当 Wi-Fi 和 ESP-BLE-MESH 共存时，搭载 PSRAM 的 ESP32-DevKitC 速率可以稳定在 1 Mbps 以上。
 
     应使能 menuconfig 中的一些配置来支持 PSRAM。
 
-        - :code:`ESP32-specific --> Support for external,SPI-connected RAM --> Try to allocate memories of Wi-Fi and LWIP...`
+        - :code:`{IDF_TARGET_NAME}-specific --> Support for external,SPI-connected RAM --> Try to allocate memories of Wi-Fi and LWIP...`
         - :code:`Bluetooth --> Bluedriod Enable --> BT/BLE will first malloc the memory from the PSRAM`
         - :code:`Bluetooth --> Bluedriod Enable --> Use dynamic memory allocation in BT/BLE stack.`
         - :code:`Bluetooth --> Blutooth controller --> BLE full scan feature supported.`

docs/zh_CN/api-reference/peripherals/touch_pad.rst

@@ -25,7 +25,7 @@
 
 .. only:: SOC_TOUCH_VERSION_1
 
-	如果想评估触摸传感器的多种应用场景，请查看 `ESP32 触摸功能开发套件 <https://github.com/espressif/esp-dev-kits/blob/master/esp32-sense-kit/docs/esp32_sense_kit_guide_en.md>`_。
+	如果想评估触摸传感器的多种应用场景，请查看 `ESP32 触摸功能开发套件 <https://docs.espressif.com/projects/espressif-esp-dev-kits/en/latest/esp32/esp32-sense-kit/user_guide.html>`_。
 
 功能介绍
 ----------------------

docs/zh_CN/hw-reference/esp32/user-guide-devkits-r-v1.1.rst

@@ -9,9 +9,9 @@ ESP32-DevKitS(-R)
 ESP32-DevKitS(-R) 包括两款开发板，分别是 ESP32-DevKitS 和 ESP32-DevKitS-R。S 代表弹簧 (spring)，R 代表 WROVER 模组。
 
 +-----------------+-------------------+
-| |ESP32-DevKitS| | |ESP32-DevKitS-R| | 
+| |ESP32-DevKitS| | |ESP32-DevKitS-R| |
 +-----------------+-------------------+
-|  ESP32-DevKitS  |  ESP32-DevKitS-R  | 
+|  ESP32-DevKitS  |  ESP32-DevKitS-R  |
 +-----------------+-------------------+
 
 .. |ESP32-DevKitS| image:: ../../../_static/esp32-devkits-v1.1-layout-isometric-raw.png
@@ -146,14 +146,14 @@ Windows 用户也可以使用 `Flash 下载工具 <https://www.espressif.com/zh-
     :align: center
     :alt: ESP32-DevKitS - 背面
     :figclass: align-center
-    
+
     ESP32-DevKitS 尺寸 - 背面
 
 .. figure:: ../../../_static/esp32-devkits-r-v1.1-dimensions-back.png
     :align: center
     :alt: ESP32-DevKitS-R - 背面
     :figclass: align-center
-    
+
     ESP32-DevKitS-R 尺寸 - 背面
 
 
@@ -263,6 +263,6 @@ R19      CLK               SD_CLK
 - `ESP32-WROOM-32 技术规格书 <https://espressif.com/sites/default/files/documentation/esp32-wroom-32_datasheet_cn.pdf>`_ (PDF)
 - `ESP32-WROOM-32D & ESP32-WROOM-32U 技术规格书 <https://www.espressif.com/sites/default/files/documentation/esp32-wroom-32d_esp32-wroom-32u_datasheet_cn.pdf>`_ (PDF)
 - `ESP32-SOLO-1 技术规格书 <https://www.espressif.com/sites/default/files/documentation/esp32-solo-1_datasheet_cn.pdf>`_ (PDF)
-- `ESP32-WROVER 技术规格书 <https://espressif.com/sites/default/files/documentation/esp32-wrover_datasheet_cn.pdf>`_ (PDF)
+- `ESP32-WROVER 技术规格书 <https://espressif.com/sites/default/files/documentation/esp32_wrover_datasheet_cn.pdf>`_ (PDF)
 - `ESP32-WROVER-B 技术规格书 <https://www.espressif.com/sites/default/files/documentation/esp32-wrover-b_datasheet_cn.pdf>`_ (PDF)
-- `乐鑫产品选型工具 <https://products.espressif.com/#/product-selector?names=>`__
+- `乐鑫产品选型工具 <https://products.espressif.com/#/product-selector?names=>`__