docs: fix all doxygen warnings

Doxygen warnings would previously not result in a failed pipeline.
Fixed this as well as all current warnings.

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).
+ * 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.
+ * 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.
+ * 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/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;
+    } flags;                               /*!< LCD panel config flags */
-    void *vendor_config; /* vendor specific configuration, optional, left as NULL if not used */
+    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];
+    uint32_t addr[4]; /*!< IPv6 address */
-    uint8_t zone;
+    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_ip6_addr_t ip6; /*!< IPv6 address type */
-        esp_ip4_addr_t ip4;
+        esp_ip4_addr_t ip4; /*!< IPv4 address type */
-    } u_addr;
+    } u_addr;               /*!< IP address union */
-    uint8_t type;
+    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_err_t (*post_attach)(esp_netif_t *netif, esp_netif_iodriver_handle h); /*!< post attach function pointer */
-    esp_netif_t *netif;
+    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_netif_iodriver_handle handle; /*!< io-driver handle */
-    esp_err_t (*transmit)(void *h, void *buffer, size_t len);
+    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);
+    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);
+    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_inherent_config_t *base; /*!< base config */
-    const esp_netif_driver_ifconfig_t *driver;
+    const esp_netif_driver_ifconfig_t *driver; /*!< driver config */
-    const esp_netif_netstack_config_t *stack;
+    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
+/*
-//
+ * SPDX-FileCopyrightText: 2016-2022 Espressif Systems (Shanghai) CO LTD
-// Licensed under the Apache License, Version 2.0 (the "License");
+ *
-// you may not use this file except in compliance with the License.
+ * SPDX-License-Identifier: Apache-2.0
-// 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.
 
 #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
+/*
-//
+ * SPDX-FileCopyrightText: 2016-2022 Espressif Systems (Shanghai) CO LTD
-// Licensed under the Apache License, Version 2.0 (the "License");
+ *
-// you may not use this file except in compliance with the License.
+ * SPDX-License-Identifier: Apache-2.0
-// 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.
 
 #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
+/*
-//
+ * SPDX-FileCopyrightText: 2016-2022 Espressif Systems (Shanghai) CO LTD
-// Licensed under the Apache License, Version 2.0 (the "License");
+ *
-// you may not use this file except in compliance with the License.
+ * SPDX-License-Identifier: Apache-2.0
-// 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.
 
 #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;
+    } USB_DESC_ATTR;                        /**< USB descriptor attributes */
-    uint8_t val[USB_STANDARD_DESC_SIZE];
+    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;
+    } USB_DESC_ATTR;                        /**< USB descriptor attributes */
-    uint8_t val[USB_DEVICE_DESC_SIZE];
+    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;
+    } USB_DESC_ATTR;                        /**< USB descriptor attributes */
-    uint8_t val[USB_CONFIG_DESC_SIZE];
+    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;
+    } USB_DESC_ATTR;                        /**< USB descriptor attributes */
-    uint8_t val[USB_IAD_DESC_SIZE];
+    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;
+    } USB_DESC_ATTR;                        /**< USB descriptor attributes */
-    uint8_t val[USB_INTF_DESC_SIZE];
+    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;
+    } USB_DESC_ATTR;                        /**< USB descriptor attributes */
-    uint8_t val[USB_EP_DESC_SIZE];
+    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;
+    } USB_DESC_ATTR;                        /**< USB descriptor attributes */
-    uint8_t val[USB_STR_DESC_SIZE];
+    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
 

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,7 @@ 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"
 
@@ -277,6 +274,5 @@ QUIET = YES
 
 ## Enable Section Tags for conditional documentation
 ##
-ENABLED_SECTIONS += \
+ENABLED_SECTIONS += DOC_EXCLUDE_HEADER_SECTION  ## To conditionally remove doc sections from IDF source files without affecting documentation in upstream files.
-    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.
-    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/requirements.txt

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

docs/sphinx-known-warnings.txt

@@ -6,12 +6,20 @@
 #
 # Warnings in this file must be in the same overall order as the log file.
 #
+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 [ESP_BD_ADDR_LEN]'.
+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.