Merge branch 'bugfix/fix_doxygen_warnings' into 'master'

docs: fix  doxygen warnings

See merge request espressif/esp-idf!18071

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, ESP32-S3, ESP32-C3, ESP32-H2 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, ESP32-H2 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_hf_client_api.h

@@ -583,7 +583,7 @@ esp_err_t esp_hf_client_send_dtmf(char code);
  *                               vendorID: A string representation of the hex value of the vendor ID from the manufacturer, without the 0x prefix.
  *                               productID: A string representation of the hex value of the product ID from the manufacturer, without the 0x prefix.
  *                               version: The revision of the software
- *                  features: A base-10 representation of a bit field. such as ESP_HF_CLIENT_XAPL_FEAT_BATTERY_REPORT
+ * @param[in]       features: A base-10 representation of a bit field. such as ESP_HF_CLIENT_XAPL_FEAT_BATTERY_REPORT
  *
  * @return
  *                  - ESP_OK: Feature enable request is sent to lower layer
@@ -601,7 +601,7 @@ esp_err_t esp_hf_client_send_xapl(char *information, uint32_t features);
  *
  *
  * @param[in]       bat_level: Battery Level: value between 0 and 9
- *                  docked: Dock State: false = undocked, true = docked
+ * @param[in]       docked: Dock State: false = undocked, true = docked
  *
  * @return
  *                  - ESP_OK: battery level is sent to lower layer

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

@@ -81,7 +81,7 @@ typedef enum {
 } esp_hidd_boot_report_id_t;
 
 /**
- * @breif HID Boot Protocol report size including report ID
+ * @brief HID Boot Protocol report size including report ID
  */
 enum {
     ESP_HIDD_BOOT_REPORT_SIZE_KEYBOARD = 9,          /*!< report size of Boot Protocol keyboard report */

components/driver/include/driver/gptimer.h

@@ -57,7 +57,7 @@ typedef struct {
                                               hence, the step size of each count tick equals to (1 / resolution_hz) seconds */
     struct {
         uint32_t intr_shared: 1;         /*!< Set true, the timer interrupt number can be shared with other peripherals */
-    } flags;
+    } flags;                             /*!< GPTimer config flags*/
 } gptimer_config_t;
 
 /**
@@ -68,7 +68,7 @@ typedef struct {
     uint64_t reload_count; /*!< Alarm reload count value, effect only when `auto_reload_on_alarm` is set to true */
     struct {
         uint32_t auto_reload_on_alarm: 1; /*!< Reload the count value by hardware, immediately at the alarm event */
-    } flags;
+    } flags;                              /*!< Alarm config flags*/
 } gptimer_alarm_config_t;
 
 /**

components/driver/include/driver/pulse_cnt.h

@@ -73,7 +73,7 @@ typedef struct {
         uint32_t invert_edge_input: 1;  /*!< Invert the input edge signal */
         uint32_t invert_level_input: 1; /*!< Invert the input level signal */
         uint32_t io_loop_back: 1;       /*!< For debug/test, the signal output from the GPIO will be fed to the input path as well */
-    } flags;
+    } flags;                            /*!< Channel config flags */
 } pcnt_chan_config_t;
 
 /**

components/driver/include/driver/rmt_common.h

@@ -23,7 +23,7 @@ typedef struct {
     struct {
         uint32_t polarity_active_low: 1; /*!< Specify the polarity of carrier, by default it's modulated to base signal's high level */
         uint32_t always_on: 1;           /*!< If set, the carrier can always exist even there's not transfer undergoing */
-    } flags;
+    } flags;                             /*!< Carrier config flags */
 } rmt_carrier_config_t;
 
 /**

components/driver/include/driver/rmt_encoder.h

@@ -76,7 +76,7 @@ typedef struct {
     rmt_symbol_word_t bit1; /*!< How to represent BIT1 in RMT symbol */
     struct {
         uint32_t msb_first: 1; /*!< Whether to encode MSB bit first */
-    } flags;
+    } flags;                   /*!< Encoder config flag */
 } rmt_bytes_encoder_config_t;
 
 /**

components/driver/include/driver/rmt_rx.h

@@ -37,7 +37,7 @@ typedef struct {
         uint32_t invert_in: 1;    /*!< Whether to invert the incoming RMT channel signal */
         uint32_t with_dma: 1;     /*!< If set, the driver will allocate an RMT channel with DMA capability */
         uint32_t io_loop_back: 1; /*!< For debug/test, the signal output from the GPIO will be fed to the input path as well */
-    } flags;
+    } flags;                      /*!< RX channel config flags */
 } rmt_rx_channel_config_t;
 
 /**

components/driver/include/driver/rmt_tx.h

@@ -39,7 +39,7 @@ typedef struct {
         uint32_t invert_out: 1;   /*!< Whether to invert the RMT channel signal before output to GPIO pad */
         uint32_t with_dma: 1;     /*!< If set, the driver will allocate an RMT channel with DMA capability */
         uint32_t io_loop_back: 1; /*!< For debug/test, the signal output from the GPIO will be fed to the input path as well */
-    } flags;
+    } flags;                      /*!< TX channel config flags */
 } rmt_tx_channel_config_t;
 
 /**
@@ -49,7 +49,7 @@ typedef struct {
     int loop_count; /*!< Specify the times of transmission in a loop, -1 means transmitting in an infinite loop */
     struct {
         uint32_t eot_level : 1; /*!< Set the output level for the "End Of Transmission" */
-    } flags;
+    } flags;                    /*!< Transmit config flags */
 } rmt_transmit_config_t;
 
 /**

components/driver/include/driver/temperature_sensor.h

@@ -26,9 +26,9 @@ typedef struct temperature_sensor_obj_t *temperature_sensor_handle_t;
  *       predefined range listed doc ``api-reference/peripherals/Temperature sensor``.
  */
 typedef struct {
-    int range_min;   // the minimum value of the temperature you want to test
-    int range_max;   // the maximum value of the temperature you want to test
-    temperature_sensor_clk_src_t clk_src;  // the clock source of the temperature sensor.
+    int range_min;   /**< the minimum value of the temperature you want to test */
+    int range_max;   /**< the maximum value of the temperature you want to test */
+    temperature_sensor_clk_src_t clk_src;  /**< the clock source of the temperature sensor. */
 } temperature_sensor_config_t;
 
 /**

components/esp_eth/include/esp_eth_mac.h

@@ -457,7 +457,8 @@ typedef struct {
 /**
 * @brief Create ESP32 Ethernet MAC instance
 *
-* @param config: Ethernet MAC configuration
+* @param esp32_config: EMAC specific configuration
+* @param config:       Ethernet MAC configuration
 *
 * @return
 *      - instance: create MAC instance successfully

components/esp_https_server/include/esp_https_server.h

@@ -35,8 +35,8 @@ typedef enum {
  * and the connection state at which the callback is executed
  */
 typedef struct esp_https_server_user_cb_arg {
-    httpd_ssl_user_cb_state_t user_cb_state;
-    esp_tls_t *tls;
+    httpd_ssl_user_cb_state_t user_cb_state; /*!< State of user callback */
+    esp_tls_t *tls;                    /*!< ESP-TLS connection handle */
 } esp_https_server_user_cb_arg_t;
 
 /**

components/esp_hw_support/include/esp_mac.h

@@ -146,7 +146,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 on 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 */
@@ -166,6 +171,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 */
@@ -187,19 +196,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;
@@ -214,9 +227,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_netif/include/esp_vfs_l2tap.h

@@ -20,8 +20,12 @@ extern "C" {
 
 typedef void *l2tap_iodriver_handle;
 
+/**
+ * @brief L2Tap VFS config parameters
+ *
+ */
 typedef struct {
-    const char* base_path;
+    const char* base_path; /*!< vfs base path */
 } l2tap_vfs_config_t;
 
 typedef enum {
@@ -56,7 +60,7 @@ esp_err_t esp_vfs_l2tap_intf_unregister(const char *base_path);
 /**
  * @brief Filters received Ethernet L2 frames into L2 TAP infrastructure.
  *
- * @param eth_hdl handle of Ethernet driver at which the frame was received
+ * @param driver_handle handle of driver at which the frame was received
  * @param buff received L2 frame
  * @param size input length of the L2 frame which is set to 0 when frame is filtered into L2 TAP
  * @return esp_err_t

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. */
@@ -208,6 +213,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/FreeRTOS-Kernel/include/freertos/queue.h

@@ -1405,9 +1405,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/FreeRTOS-Kernel/include/freertos/task.h

@@ -393,7 +393,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
@@ -539,7 +539,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.
  *
@@ -2369,7 +2369,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.
  *
@@ -2524,6 +2524,10 @@ BaseType_t xTaskGenericNotify( TaskHandle_t xTaskToNotify,
  * updated.  ulValue is not used and xTaskNotify() always returns pdPASS in
  * this case.
  *
+ * @param pulPreviousNotificationValue -
+ * Can be used to pass out the subject task's notification value before any
+ * bits are modified by the notify function.
+ *
  * @param pxHigherPriorityTaskWoken  xTaskNotifyFromISR() will set
  * *pxHigherPriorityTaskWoken to pdTRUE if sending the notification caused the
  * task to which the notification was sent to leave the Blocked state, and the
@@ -2779,10 +2783,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

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/clk_tree_defs.h

@@ -44,10 +44,10 @@ extern "C" {
 
 /**
  * @brief Root clock
- * Naming convention: SOC_ROOT_CLK_{loc}_{type}_<attr>
+ * Naming convention: SOC_ROOT_CLK_{loc}_{type}_[attr]
  * {loc}: EXT, INT
  * {type}: XTAL, RC
- * <attr> - optional: <frequency>, FAST, SLOW
+ * [attr] - optional: [frequency], FAST, SLOW
  */
 typedef enum {
     SOC_ROOT_CLK_INT_RC_FAST,          /*!< Internal 8MHz RC oscillator */
@@ -86,9 +86,9 @@ typedef enum {
 
 /**
  * @brief Supported clock sources for modules (CPU, peripherials, RTC, etc.)
- * Naming convention: SOC_MOD_CLK_{<upstream>clock_name}_<attr>
- * {<upstream>clock_name}: APB, APLL, (BB)PLL, etc.
- * <attr> - optional: FAST, SLOW, D<divider>, F<freq>
+ * Naming convention: SOC_MOD_CLK_{[upstream]clock_name}_[attr]
+ * {[upstream]clock_name}: APB, APLL, (BB)PLL, etc.
+ * [attr] - optional: FAST, SLOW, D<divider>, F<freq>
  * @note enum starts from 1, to save 0 for special purpose
  */
 typedef enum {

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

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

components/soc/esp32c2/include/soc/clk_tree_defs.h

@@ -43,10 +43,10 @@ extern "C" {
 
 /**
  * @brief Root clock
- * Naming convention: SOC_ROOT_CLK_{loc}_{type}_<attr>
+ * Naming convention: SOC_ROOT_CLK_{loc}_{type}_[attr]
  * {loc}: EXT, INT
  * {type}: XTAL, RC
- * <attr> - optional: <frequency>, FAST, SLOW
+ * [attr] - optional: [frequency], FAST, SLOW
  */
 typedef enum {
     SOC_ROOT_CLK_INT_RC_FAST,          /*!< Internal 8MHz RC oscillator */
@@ -84,9 +84,9 @@ typedef enum {
 
 /**
  * @brief Supported clock sources for modules (CPU, peripherials, RTC, etc.)
- * Naming convention: SOC_MOD_CLK_{<upstream>clock_name}_<attr>
- * {<upstream>clock_name}: (BB)PLL etc.
- * <attr> - optional: FAST, SLOW, D<divider>, F<freq>
+ * Naming convention: SOC_MOD_CLK_{[upstream]clock_name}_[attr]
+ * {[upstream]clock_name}: (BB)PLL etc.
+ * [attr] - optional: FAST, SLOW, D<divider>, F<freq>
  * @note enum starts from 1, to save 0 for special purpose
  */
 typedef enum {

components/soc/esp32c3/include/soc/clk_tree_defs.h

@@ -44,10 +44,10 @@ extern "C" {
 
 /**
  * @brief Root clock
- * Naming convention: SOC_ROOT_CLK_{loc}_{type}_<attr>
+ * Naming convention: SOC_ROOT_CLK_{loc}_{type}_[attr]
  * {loc}: EXT, INT
  * {type}: XTAL, RC
- * <attr> - optional: <frequency>, FAST, SLOW
+ * [attr] - optional: [frequency], FAST, SLOW
  */
 typedef enum {
     SOC_ROOT_CLK_INT_RC_FAST,          /*!< Internal 8MHz RC oscillator */
@@ -85,9 +85,9 @@ typedef enum {
 
 /**
  * @brief Supported clock sources for modules (CPU, peripherials, RTC, etc.)
- * Naming convention: SOC_MOD_CLK_{<upstream>clock_name}_<attr>
- * {<upstream>clock_name}: APB, (BB)PLL, etc.
- * <attr> - optional: FAST, SLOW, D<divider>, F<freq>
+ * Naming convention: SOC_MOD_CLK_{[upstream]clock_name}_[attr]
+ * {[upstream]clock_name}: APB, (BB)PLL, etc.
+ * [attr] - optional: FAST, SLOW, D<divider>, F<freq>
  * @note enum starts from 1, to save 0 for special purpose
  */
 typedef enum {

components/soc/esp32h2/include/soc/clk_tree_defs.h

@@ -50,10 +50,10 @@ extern "C" {
 
 /**
  * @brief Root clock
- * Naming convention: SOC_ROOT_CLK_{loc}_{type}_<attr>
+ * Naming convention: SOC_ROOT_CLK_{loc}_{type}_[attr]
  * {loc}: EXT, INT
  * {type}: XTAL, RC
- * <attr> - optional: <frequency>, FAST, SLOW
+ * [attr] - optional: [frequency], FAST, SLOW
  */
 typedef enum {
     SOC_ROOT_CLK_INT_RC_FAST,          /*!< Internal 8MHz RC oscillator */
@@ -93,9 +93,9 @@ typedef enum {
 
 /**
  * @brief Supported clock sources for modules (CPU, peripherials, RTC, etc.)
- * Naming convention: SOC_MOD_CLK_{<upstream>clock_name}_<attr>
- * {<upstream>clock_name}: AHB etc.
- * <attr> - optional: FAST, SLOW, D<divider>, F<freq>
+ * Naming convention: SOC_MOD_CLK_{[upstream]clock_name}_[attr]
+ * {[upstream]clock_name}: AHB etc.
+ * [attr] - optional: FAST, SLOW, D<divider>, F<freq>
  * @note enum starts from 1, to save 0 for special purpose
  */
 typedef enum {

components/soc/esp32s2/include/soc/clk_tree_defs.h

@@ -44,10 +44,10 @@ extern "C" {
 
 /**
  * @brief Root clock
- * Naming convention: SOC_ROOT_CLK_{loc}_{type}_<attr>
+ * Naming convention: SOC_ROOT_CLK_{loc}_{type}_[attr]
  * {loc}: EXT, INT
  * {type}: XTAL, RC
- * <attr> - optional: <frequency>, FAST, SLOW
+ * [attr] - optional: [frequency], FAST, SLOW
  */
 typedef enum {
     SOC_ROOT_CLK_INT_RC_FAST,          /*!< Internal 8MHz RC oscillator */
@@ -86,9 +86,9 @@ typedef enum {
 
 /**
  * @brief Supported clock sources for modules (CPU, peripherials, RTC, etc.)
- * Naming convention: SOC_MOD_CLK_{<upstream>clock_name}_<attr>
- * {<upstream>clock_name}: APB, APLL, (BB)PLL, etc.
- * <attr> - optional: FAST, SLOW, D<divider>, F<freq>
+ * Naming convention: SOC_MOD_CLK_{[upstream]clock_name}_[attr]
+ * {[upstream]clock_name}: APB, APLL, (BB)PLL, etc.
+ * [attr] - optional: FAST, SLOW, D<divider>, F<freq>
  * @note enum starts from 1, to save 0 for special purpose
  */
 typedef enum {

components/soc/esp32s3/include/soc/clk_tree_defs.h

@@ -44,10 +44,10 @@ extern "C" {
 
 /**
  * @brief Root clock
- * Naming convention: SOC_ROOT_CLK_{loc}_{type}_<attr>
+ * Naming convention: SOC_ROOT_CLK_{loc}_{type}_[attr]
  * {loc}: EXT, INT
  * {type}: XTAL, RC
- * <attr> - optional: <frequency>, FAST, SLOW
+ * [attr] - optional: [frequency], FAST, SLOW
  */
 typedef enum {
     SOC_ROOT_CLK_INT_RC_FAST,          /*!< Internal 8MHz RC oscillator */
@@ -85,9 +85,9 @@ typedef enum {
 
 /**
  * @brief Supported clock sources for modules (CPU, peripherials, RTC, etc.)
- * Naming convention: SOC_MOD_CLK_{<upstream>clock_name}_<attr>
- * {<upstream>clock_name}: APB, (BB)PLL, etc.
- * <attr> - optional: FAST, SLOW, D<divider>, F<freq>
+ * Naming convention: SOC_MOD_CLK_{[upstream]clock_name}_[attr]
+ * {[upstream]clock_name}: APB, (BB)PLL, etc.
+ * [attr] - optional: FAST, SLOW, D<divider>, F<freq>
  * @note enum starts from 1, to save 0 for special purpose
  */
 typedef enum {

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/ulp/ulp_riscv/include/ulp_riscv.h

@@ -20,8 +20,12 @@ typedef enum {
     ULP_RISCV_WAKEUP_SOURCE_GPIO,
 } ulp_riscv_wakeup_source_t;
 
+/**
+ * @brief ULP riscv init parameters
+ *
+ */
 typedef struct {
-    ulp_riscv_wakeup_source_t wakeup_source;
+    ulp_riscv_wakeup_source_t wakeup_source; /*!< ULP wakeup source */
 } ulp_riscv_cfg_t;
 
 #define ULP_RISCV_DEFAULT_CONFIG()                      \

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/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

@@ -258,6 +258,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"
 
@@ -282,6 +283,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/requirements.txt

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

tools/ci/check_copyright_ignore.txt

@@ -1613,10 +1613,7 @@ components/tcp_transport/test/test_transport_fixtures.c
 components/tcp_transport/transport_utils.c
 components/tinyusb/additions/include/tusb_config.h
 components/touch_element/include/touch_element/touch_button.h
-components/touch_element/include/touch_element/touch_element.h
 components/touch_element/include/touch_element/touch_element_private.h
-components/touch_element/include/touch_element/touch_matrix.h
-components/touch_element/include/touch_element/touch_slider.h
 components/touch_element/test/test_touch_button.c
 components/touch_element/test/test_touch_element.c
 components/touch_element/test/test_touch_matrix.c