docs: Resolve doxygen & Sphinx warnings

components/bt/esp_ble_mesh/api/esp_ble_mesh_defs.h

@@ -439,11 +439,11 @@ typedef struct {
 struct esp_ble_mesh_model {
     /** Model ID */
     union {
-        const uint16_t model_id;
-        struct {
-            uint16_t company_id;
-            uint16_t model_id;
-        } vnd;
+        const uint16_t model_id; /*!< 16-bit model identifier */
+        struct esp_ble_mesh_vnd_struct {
+            uint16_t company_id; /*!< 16-bit company identifier */
+            uint16_t model_id; /*!< 16-bit model identifier */
+        } vnd; /*!< Structure encapsulating a model ID with a company ID */
     };
 
     /** Internal information, mainly for persistent storage */
@@ -656,7 +656,7 @@ typedef struct {
 typedef struct {
     union {
         struct {
-            esp_ble_mesh_bd_addr_t addr;             /*!< Device address */
+            esp_ble_mesh_bd_addr_t addr;         /*!< Device address */
             esp_ble_mesh_addr_type_t addr_type;  /*!< Device address type */
         };
         uint8_t uuid[16];                   /*!< Device UUID */

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

@@ -31,18 +31,19 @@ extern "C" {
 
 typedef uint8_t esp_a2d_mct_t;
 
-/// A2DP media codec capabilities union
+/** A2DP media codec capabilities union
+ */
 typedef struct {
     esp_a2d_mct_t type;                        /*!< A2DP media codec type */
 #define ESP_A2D_CIE_LEN_SBC          (4)
 #define ESP_A2D_CIE_LEN_M12          (4)
 #define ESP_A2D_CIE_LEN_M24          (6)
 #define ESP_A2D_CIE_LEN_ATRAC        (7)
     union {
-        uint8_t sbc[ESP_A2D_CIE_LEN_SBC];
-        uint8_t m12[ESP_A2D_CIE_LEN_M12];
-        uint8_t m24[ESP_A2D_CIE_LEN_M24];
-        uint8_t atrac[ESP_A2D_CIE_LEN_ATRAC];
+        uint8_t sbc[ESP_A2D_CIE_LEN_SBC];      /*!< SBC codec capabilities */
+        uint8_t m12[ESP_A2D_CIE_LEN_M12];      /*!< MPEG-1,2 audio codec capabilities */
+        uint8_t m24[ESP_A2D_CIE_LEN_M24];      /*!< MPEG-2, 4 AAC audio codec capabilities */
+        uint8_t atrac[ESP_A2D_CIE_LEN_ATRAC];  /*!< ATRAC family codec capabilities */
     } cie;                                     /*!< A2DP codec information element */
 } __attribute__((packed)) esp_a2d_mcc_t;
 

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

@@ -86,9 +86,9 @@ typedef struct {
 #define ESP_UUID_LEN_128    16
     uint16_t len;							/*!< UUID length, 16bit, 32bit or 128bit */
     union {
-        uint16_t    uuid16;
-        uint32_t    uuid32;
-        uint8_t     uuid128[ESP_UUID_LEN_128];
+        uint16_t    uuid16;                 /*!< 16bit UUID */
+        uint32_t    uuid32;                 /*!< 32bit UUID */
+        uint8_t     uuid128[ESP_UUID_LEN_128]; /*!< 128bit UUID */
     } uuid;									/*!< UUID */
 } __attribute__((packed)) esp_bt_uuid_t;
 

components/driver/esp32s2/include/touch_sensor.h

@@ -51,22 +51,22 @@ esp_err_t touch_pad_sw_start(void);
  *                    sleep_cycle decide the interval between each measurement.
  *                    t_sleep = sleep_cycle / (RTC_SLOW_CLK frequency).
  *                    The approximate frequency value of RTC_SLOW_CLK can be obtained using rtc_clk_slow_freq_get_hz function.
- * @param meas_timers The times of charge and discharge in each measure process of touch channels.
- *                    The timer frequency is 8Mhz. Range: 0 ~ 0xffff.
- *                    Recommended typical value: Modify this value to make the measurement time around 1ms.
+ * @param meas_time The time of charge and discharge in each measure process of touch channels.
+ *                  The timer frequency is 8Mhz. Range: 0 ~ 0xffff.
+ *                  Recommended typical value: Modify this value to make the measurement time around 1ms.
  * @return
  *      - ESP_OK on success
  */
-esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_times);
+esp_err_t touch_pad_set_meas_time(uint16_t sleep_cycle, uint16_t meas_time);
 
 /**
  * @brief Get touch sensor times of charge and discharge and sleep time
  * @param sleep_cycle  Pointer to accept sleep cycle number
- * @param meas_times Pointer to accept measurement times count.
+ * @param meas_time Pointer to accept measurement time count.
  * @return
  *      - ESP_OK on success
  */
-esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_times);
+esp_err_t touch_pad_get_meas_time(uint16_t *sleep_cycle, uint16_t *meas_time);
 
 /**
  * @brief Set connection type of touch channel in idle status.
@@ -196,15 +196,15 @@ uint32_t touch_pad_read_intr_status_mask(void);
 
 /**
  * @brief Enable touch sensor interrupt by bitmask.
- * @param type interrupt type
+ * @param int_mask Pad mask to enable interrupts
  * @return
  *      - ESP_OK on success
  */
 esp_err_t touch_pad_intr_enable(touch_pad_intr_mask_t int_mask);
 
 /**
  * @brief Disable touch sensor interrupt by bitmask.
- * @param type interrupt type
+ * @param int_mask Pad mask to disable interrupts
  * @return
  *      - ESP_OK on success
  */
@@ -215,12 +215,13 @@ esp_err_t touch_pad_intr_disable(touch_pad_intr_mask_t int_mask);
  *          The handler will be attached to the same CPU core that this function is running on.
  * @param fn  Pointer to ISR handler
  * @param arg  Parameter for ISR
+ * @param int_mask Initial pad mask to enable interrupt for
  * @return
  *     - ESP_OK Success ;
  *     - ESP_ERR_INVALID_ARG GPIO error
  *     - ESP_ERR_NO_MEM No memory
  */
-esp_err_t touch_pad_isr_register(intr_handler_t fn, void* arg, touch_pad_intr_mask_t intr_mask);
+esp_err_t touch_pad_isr_register(intr_handler_t fn, void* arg, touch_pad_intr_mask_t int_mask);
 
 /**
  * @brief get raw data of touch sensor.
@@ -239,7 +240,7 @@ esp_err_t touch_pad_read_raw_data(touch_pad_t touch_num, uint32_t *raw_data);
  * @brief get baseline of touch sensor.
  * @note After initialization, the baseline value is the maximum during the first measurement period.
  * @param touch_num touch pad index
- * @param touch_value pointer to accept touch sensor value
+ * @param basedata pointer to accept touch sensor baseline value
  * @return
  *     - ESP_OK Success
  *     - ESP_ERR_INVALID_ARG Touch channel 0 havent this parameter.
@@ -331,7 +332,7 @@ esp_err_t touch_pad_denoise_disable(void);
 
 /**
  * @brief Get denoise measure value (TOUCH_PAD_NUM0).
- * @param denoise value of denoise
+ * @param data Pointer to receive denoise value
  * @return
  *     - ESP_OK Success
  */
@@ -405,7 +406,7 @@ esp_err_t touch_pad_proximity_get_config(touch_pad_proximity_t *proximity);
  * @brief Get measure count of proximity channel.
  *        The proximity sensor measurement is the accumulation of touch channel measurements.
  * @param touch_num touch pad index
- * @param proximity parameter of proximity
+ * @param cnt Pointer to receive proximity channel measurement count
  * @return
  *     - ESP_OK Success
  *     - ESP_ERR_INVALID_ARG parameter is NULL
@@ -462,4 +463,4 @@ esp_err_t touch_pad_sleep_channel_read_proximity_cnt(uint32_t *proximity_cnt);
 
 #ifdef __cplusplus
 }
-#endif
+#endif

components/driver/include/driver/timer.h

@@ -331,8 +331,6 @@ esp_err_t timer_disable_intr(timer_group_t group_num, timer_idx_t timer_num);
  * @param group_num Timer group number, 0 for TIMERG0 or 1 for TIMERG1
  * @param timer_num Timer index.
  *
- * @return
- *     - None
  */
 void timer_group_intr_clr_in_isr(timer_group_t group_num, timer_idx_t timer_num) __attribute__((deprecated));
 
@@ -341,8 +339,6 @@ void timer_group_intr_clr_in_isr(timer_group_t group_num, timer_idx_t timer_num)
  * @param group_num Timer group number, 0 for TIMERG0 or 1 for TIMERG1
  * @param timer_num Timer index.
  *
- * @return
- *     - None
  */
 void timer_group_clr_intr_status_in_isr(timer_group_t group_num, timer_idx_t timer_num);
 
@@ -351,8 +347,6 @@ void timer_group_clr_intr_status_in_isr(timer_group_t group_num, timer_idx_t tim
  * @param group_num Timer group number, 0 for TIMERG0 or 1 for TIMERG1
  * @param timer_num Timer index.
  *
- * @return
- *     - None
  */
 void timer_group_enable_alarm_in_isr(timer_group_t group_num, timer_idx_t timer_num);
 
@@ -372,8 +366,6 @@ uint64_t timer_group_get_counter_value_in_isr(timer_group_t group_num, timer_idx
  * @param timer_num Timer index.
  * @param alarm_val Alarm threshold.
  *
- * @return
- *     - None
  */
 void timer_group_set_alarm_value_in_isr(timer_group_t group_num, timer_idx_t timer_num, uint64_t alarm_val);
 
@@ -383,8 +375,6 @@ void timer_group_set_alarm_value_in_isr(timer_group_t group_num, timer_idx_t tim
  * @param timer_num Timer index.
  * @param counter_en Enable/disable.
  *
- * @return
- *     - None
  */
 void timer_group_set_counter_enable_in_isr(timer_group_t group_num, timer_idx_t timer_num, timer_start_t counter_en);
 
@@ -411,8 +401,6 @@ uint32_t timer_group_get_intr_status_in_isr(timer_group_t group_num);
  * @param group_num Timer group number, 0 for TIMERG0 or 1 for TIMERG1
  * @param intr_mask Masked interrupt.
  *
- * @return
- *     - None
  */
 void timer_group_clr_intr_sta_in_isr(timer_group_t group_num, timer_intr_t intr_mask) __attribute__((deprecated));
 

components/esp32/include/esp_intr_alloc.h

@@ -56,7 +56,6 @@ extern "C" {
 #define ESP_INTR_FLAG_LEVELMASK	(ESP_INTR_FLAG_LEVEL1|ESP_INTR_FLAG_LEVEL2|ESP_INTR_FLAG_LEVEL3| \
 								 ESP_INTR_FLAG_LEVEL4|ESP_INTR_FLAG_LEVEL5|ESP_INTR_FLAG_LEVEL6| \
 								 ESP_INTR_FLAG_NMI) ///< Mask for all level flags
-/**@}*/
 
 
 /** @addtogroup Intr_Alloc_Pseudo_Src
@@ -78,16 +77,23 @@ extern "C" {
 
 /**@}*/
 
-// This is used to provide SystemView with positive IRQ IDs, otherwise sheduler events are not shown properly
+/** Provides SystemView with positive IRQ IDs, otherwise scheduler events are not shown properly
+ */
 #define ETS_INTERNAL_INTR_SOURCE_OFF		(-ETS_INTERNAL_PROFILING_INTR_SOURCE)
 
+/** Enable interrupt by interrupt number */
 #define ESP_INTR_ENABLE(inum)  xt_ints_on((1<<inum))
+
+/** Disable interrupt by interrupt number */
 #define ESP_INTR_DISABLE(inum) xt_ints_off((1<<inum))
 
+/** Function prototype for interrupt handler function */
 typedef void (*intr_handler_t)(void *arg);
 
-
+/** Interrupt handler associated data structure */
 typedef struct intr_handle_data_t intr_handle_data_t;
+
+/** Handle to an interrupt handler */
 typedef intr_handle_data_t* intr_handle_t ;
 
 /**

components/esp32s2/include/esp_intr_alloc.h

@@ -56,7 +56,6 @@ extern "C" {
 #define ESP_INTR_FLAG_LEVELMASK	(ESP_INTR_FLAG_LEVEL1|ESP_INTR_FLAG_LEVEL2|ESP_INTR_FLAG_LEVEL3| \
 								 ESP_INTR_FLAG_LEVEL4|ESP_INTR_FLAG_LEVEL5|ESP_INTR_FLAG_LEVEL6| \
 								 ESP_INTR_FLAG_NMI) ///< Mask for all level flags
-/**@}*/
 
 
 /** @addtogroup Intr_Alloc_Pseudo_Src
@@ -78,16 +77,23 @@ extern "C" {
 
 /**@}*/
 
-// This is used to provide SystemView with positive IRQ IDs, otherwise sheduler events are not shown properly
+/** Provides SystemView with positive IRQ IDs, otherwise scheduler events are not shown properly
+ */
 #define ETS_INTERNAL_INTR_SOURCE_OFF		(-ETS_INTERNAL_PROFILING_INTR_SOURCE)
 
+/** Enable interrupt by interrupt number */
 #define ESP_INTR_ENABLE(inum)  xt_ints_on((1<<inum))
+
+/** Disable interrupt by interrupt number */
 #define ESP_INTR_DISABLE(inum) xt_ints_off((1<<inum))
 
+/** Function prototype for interrupt handler function */
 typedef void (*intr_handler_t)(void *arg);
 
-
+/** Interrupt handler associated data structure */
 typedef struct intr_handle_data_t intr_handle_data_t;
+
+/** Handle to an interrupt handler */
 typedef intr_handle_data_t* intr_handle_t ;
 
 /**

components/esp_event/include/esp_event.h

@@ -302,6 +302,7 @@ esp_err_t esp_event_isr_post(esp_event_base_t event_base,
 /**
  * @brief Special variant of esp_event_post_to for posting events from interrupt handlers
  *
+ * @param[in] event_loop the event loop to post to
  * @param[in] event_base the event base that identifies the event
  * @param[in] event_id the event id that identifies the event
  * @param[in] event_data the data, specific to the event occurence, that gets passed to the handler

components/freemodbus/common/include/esp_modbus_common.h

@@ -114,7 +114,7 @@ typedef union {
         uart_port_t port;                       /*!< Modbus communication port (UART) number */
         uint32_t baudrate;                      /*!< Modbus baudrate */
         uart_parity_t parity;                   /*!< Modbus UART parity settings */
-        uint16_t dummy_port;
+        uint16_t dummy_port;                    /*!< Dummy field, unused */
     };
     // Tcp communication structure
     struct {

components/soc/include/hal/i2c_types.h

@@ -83,11 +83,11 @@ typedef struct{
     union {
         struct {
             uint32_t clk_speed;     /*!< I2C clock frequency for master mode, (no higher than 1MHz for now) */
-        } master;
+        } master;                   /*!< I2C master config */
         struct {
             uint8_t addr_10bit_en;  /*!< I2C 10bit address mode enable for slave mode */
             uint16_t slave_addr;    /*!< I2C address for slave mode */
-        } slave;
+        } slave;                    /*!< I2C slave config */
     };
 } i2c_config_t;