diff --git a/components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h b/components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h
index 514e533f64..254eccf69f 100644
--- a/components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h
+++ b/components/bt/host/bluedroid/api/include/api/esp_a2dp_api.h
@@ -14,31 +14,27 @@
 extern "C" {
 #endif
 
-/**
- * @brief Media codec types supported by A2DP.
- */
+/* Media codec types supported by A2DP. */
 #define ESP_A2D_MCT_SBC         (0)             /*!< SBC */
 #define ESP_A2D_MCT_M12         (0x01)          /*!< MPEG-1, 2 Audio */
 #define ESP_A2D_MCT_M24         (0x02)          /*!< MPEG-2, 4 AAC */
 #define ESP_A2D_MCT_ATRAC       (0x04)          /*!< ATRAC family */
 #define ESP_A2D_MCT_NON_A2DP    (0xff)          /*!< NON-A2DP */
-typedef uint8_t esp_a2d_mct_t;
+typedef uint8_t esp_a2d_mct_t;                  /*!< Media codec type of A2DP */
 
-/**
- * @brief Protocol service capabilities. This value is a mask.
- */
+/* Protocol service capabilities. This value is a mask. */
 #define ESP_A2D_PSC_DELAY_RPT          (1<<0)  /*!< Delay Report */
-typedef uint16_t esp_a2d_psc_t;
+typedef uint16_t esp_a2d_psc_t;                /*!< Protocol service capabilities type */
 
 /**
  * @brief 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)
+#define ESP_A2D_CIE_LEN_SBC          (4)       /*!< SBC cie length */
+#define ESP_A2D_CIE_LEN_M12          (4)       /*!< MPEG-1,2 cie length */
+#define ESP_A2D_CIE_LEN_M24          (6)       /*!< MPEG-2,4 AAC cie length */
+#define ESP_A2D_CIE_LEN_ATRAC        (7)       /*!< ATRAC family cie length */
     union {
         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 */
@@ -100,7 +96,7 @@ typedef enum {
  */
 typedef enum {
     ESP_A2D_DEINIT_SUCCESS = 0,                /*!< A2DP profile deinit successful event */
-    ESP_A2D_INIT_SUCCESS                       /*!< A2DP profile deinit successful event */
+    ESP_A2D_INIT_SUCCESS                       /*!< A2DP profile init successful event */
 } esp_a2d_init_state_t;
 
 /**
@@ -213,9 +209,9 @@ typedef union {
 /**
  * @brief           A2DP profile callback function type
  *
- * @param           event : Event type
+ * @param[in]       event : Event type
  *
- * @param           param : Pointer to callback parameter
+ * @param[in]       param : Pointer to callback parameter
  */
 typedef void (* esp_a2d_cb_t)(esp_a2d_cb_event_t event, esp_a2d_cb_param_t *param);
 
@@ -257,7 +253,6 @@ typedef int32_t (* esp_a2d_source_data_cb_t)(uint8_t *buf, int32_t len);
  */
 esp_err_t esp_a2d_register_callback(esp_a2d_cb_t callback);
 
-
 /**
  * @brief           Register A2DP sink data output function; For now the output is PCM data stream decoded
  *                  from SBC format. This function should be called only after esp_bluedroid_enable()
@@ -274,7 +269,6 @@ esp_err_t esp_a2d_register_callback(esp_a2d_cb_t callback);
  */
 esp_err_t esp_a2d_sink_register_data_callback(esp_a2d_sink_data_cb_t callback);
 
-
 /**
  *
  * @brief           Initialize the bluetooth A2DP sink module. This function should be called
@@ -291,7 +285,6 @@ esp_err_t esp_a2d_sink_register_data_callback(esp_a2d_sink_data_cb_t callback);
  */
 esp_err_t esp_a2d_sink_init(void);
 
-
 /**
  *
  * @brief           De-initialize for A2DP sink module. This function
@@ -306,7 +299,6 @@ esp_err_t esp_a2d_sink_init(void);
  */
 esp_err_t esp_a2d_sink_deinit(void);
 
-
 /**
  *
  * @brief           Connect to remote bluetooth A2DP source device. This API must be called after
@@ -322,7 +314,6 @@ esp_err_t esp_a2d_sink_deinit(void);
  */
 esp_err_t esp_a2d_sink_connect(esp_bd_addr_t remote_bda);
 
-
 /**
  *
  * @brief           Disconnect from the remote A2DP source device. This API must be called after
@@ -368,7 +359,6 @@ esp_err_t esp_a2d_sink_set_delay_value(uint16_t delay_value);
  */
 esp_err_t esp_a2d_sink_get_delay_value(void);
 
-
 /**
  *
  * @brief           Media control commands. This API can be used for both A2DP sink and source
@@ -384,7 +374,6 @@ esp_err_t esp_a2d_sink_get_delay_value(void);
  */
 esp_err_t esp_a2d_media_ctrl(esp_a2d_media_ctrl_t ctrl);
 
-
 /**
  * @brief       This function is used to get the status of A2DP
  *
@@ -396,7 +385,6 @@ esp_err_t esp_a2d_media_ctrl(esp_a2d_media_ctrl_t ctrl);
  */
 esp_err_t esp_a2d_get_profile_status(esp_a2d_profile_status_t *profile_status);
 
-
 /**
  *
  * @brief           Initialize the bluetooth A2DP source module. A2DP can work independently.
@@ -413,7 +401,6 @@ esp_err_t esp_a2d_get_profile_status(esp_a2d_profile_status_t *profile_status);
  */
 esp_err_t esp_a2d_source_init(void);
 
-
 /**
  *
  * @brief           De-initialize for A2DP source module. This function
@@ -428,7 +415,6 @@ esp_err_t esp_a2d_source_init(void);
  */
 esp_err_t esp_a2d_source_deinit(void);
 
-
 /**
  * @brief           Register A2DP source data input function. For now, the input should be PCM data stream.
  *                  This function should be called only after esp_bluedroid_enable() completes
@@ -445,7 +431,6 @@ esp_err_t esp_a2d_source_deinit(void);
  */
 esp_err_t esp_a2d_source_register_data_callback(esp_a2d_source_data_cb_t callback);
 
-
 /**
  *
  * @brief           Connect to remote A2DP sink device. This API must be called
@@ -461,7 +446,6 @@ esp_err_t esp_a2d_source_register_data_callback(esp_a2d_source_data_cb_t callbac
  */
 esp_err_t esp_a2d_source_connect(esp_bd_addr_t remote_bda);
 
-
 /**
  *
  * @brief           Disconnect from the remote A2DP sink device. This API must be called
@@ -480,5 +464,4 @@ esp_err_t esp_a2d_source_disconnect(esp_bd_addr_t remote_bda);
 }
 #endif
 
-
 #endif /* __ESP_A2DP_API_H__ */
diff --git a/components/bt/host/bluedroid/api/include/api/esp_avrc_api.h b/components/bt/host/bluedroid/api/include/api/esp_avrc_api.h
index 15fd2c72ec..86eb6dca4e 100644
--- a/components/bt/host/bluedroid/api/include/api/esp_avrc_api.h
+++ b/components/bt/host/bluedroid/api/include/api/esp_avrc_api.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -105,7 +105,7 @@ typedef enum {
 typedef enum {
     ESP_AVRC_PSTH_FILTER_ALLOWED_CMD = 0,       /*!< all of the PASSTHROUGH commands that can possibly be used, immutable */
     ESP_AVRC_PSTH_FILTER_SUPPORTED_CMD = 1,     /*!< PASSTHROUGH commands selectively supported according to the current configuration */
-    ESP_AVRC_PSTH_FILTER_SUPPORT_MAX,
+    ESP_AVRC_PSTH_FILTER_SUPPORT_MAX,           /*!< Maximum value for PASSTHROUGH command filter */
 } esp_avrc_psth_filter_t;
 
 /// AVRC passthrough command bit mask
@@ -113,6 +113,7 @@ typedef struct {
     uint16_t bits[8];                           /*!< bit mask representation of PASSTHROUGH commands */
 } esp_avrc_psth_bit_mask_t;
 
+/// AVRC operation code bit mask
 typedef enum {
     ESP_AVRC_BIT_MASK_OP_TEST = 0,      /*!< operation code to test a specific bit */
     ESP_AVRC_BIT_MASK_OP_SET = 1,       /*!< operation code to set a specific bit  */
@@ -175,14 +176,14 @@ typedef enum {
     ESP_AVRC_RN_ADDRESSED_PLAYER_CHANGE = 0x0b,   /*!< the addressed player changed */
     ESP_AVRC_RN_UIDS_CHANGE = 0x0c,               /*!< UIDs changed */
     ESP_AVRC_RN_VOLUME_CHANGE = 0x0d,             /*!< volume changed locally on TG */
-    ESP_AVRC_RN_MAX_EVT
+    ESP_AVRC_RN_MAX_EVT                           /*!< maximum value for notification event */
 } esp_avrc_rn_event_ids_t;
 
 /// AVRC target notification event notification capability
 typedef enum {
     ESP_AVRC_RN_CAP_ALLOWED_EVT = 0,              /*!< all of the notification events that can possibly be supported, immutable */
     ESP_AVRC_RN_CAP_SUPPORTED_EVT = 1,            /*!< notification events selectively supported according to the current configuration */
-    ESP_AVRC_RN_CAP_MAX,
+    ESP_AVRC_RN_CAP_MAX,                          /*!< maximum value for the notification event capability */
 } esp_avrc_rn_evt_cap_t;
 
 /// AVRC target notification event capability bit mask
@@ -202,7 +203,7 @@ typedef enum {
     ESP_AVRC_PS_REPEAT_MODE = 0x02,               /*!< repeat mode */
     ESP_AVRC_PS_SHUFFLE_MODE = 0x03,              /*!< shuffle mode */
     ESP_AVRC_PS_SCAN_MODE = 0x04,                 /*!< scan mode on or off */
-    ESP_AVRC_PS_MAX_ATTR
+    ESP_AVRC_PS_MAX_ATTR                          /*!< Maximum value for player setting attribute ids*/
 } esp_avrc_ps_attr_ids_t;
 
 /// AVRC equalizer modes
@@ -221,9 +222,9 @@ typedef enum {
 
 /// AVRC shuffle modes
 typedef enum {
-    ESP_AVRC_PS_SHUFFLE_OFF = 0x1,                /*<! shuffle off */
-    ESP_AVRC_PS_SHUFFLE_ALL = 0x2,                /*<! shuffle all tracks */
-    ESP_AVRC_PS_SHUFFLE_GROUP = 0x3               /*<! group shuffle */
+    ESP_AVRC_PS_SHUFFLE_OFF = 0x1,                /*!< shuffle off */
+    ESP_AVRC_PS_SHUFFLE_ALL = 0x2,                /*!< shuffle all tracks */
+    ESP_AVRC_PS_SHUFFLE_GROUP = 0x3               /*!< group shuffle */
 } esp_avrc_ps_shf_value_ids_t;
 
 /// AVRC scan modes
@@ -465,7 +466,7 @@ esp_err_t esp_avrc_ct_register_callback(esp_avrc_ct_cb_t callback);
  * @brief           Initialize the bluetooth AVRCP controller module, This function should be called
  *                  after esp_bluedroid_enable() completes successfully. Note: AVRC cannot work independently,
  *                  AVRC should be used along with A2DP and AVRC should be initialized before A2DP.
- *                  ESP_AVRC_CT_PROF_STATE_EVT with ESP_AVRC_INIT_SUCCESS will reported to the APP layer.
+ *                  `ESP_AVRC_CT_PROF_STATE_EVT` with `ESP_AVRC_INIT_SUCCESS` will be reported to the APP layer.
  *
  * @return
  *                  - ESP_OK: success
@@ -478,9 +479,9 @@ esp_err_t esp_avrc_ct_init(void);
 /**
  *
  * @brief           De-initialize AVRCP controller module. This function should be called after
- *                  after esp_bluedroid_enable() completes successfully. Note: AVRC cannot work independently,
+ *                  `esp_bluedroid_enable()` completes successfully. Note: AVRC cannot work independently,
  *                  AVRC should be used along with A2DP and AVRC should be deinitialized before A2DP.
- *                  ESP_AVRC_CT_PROF_STATE_EVT with ESP_AVRC_DEINIT_SUCCESS will reported to the APP layer.
+ *                  `ESP_AVRC_CT_PROF_STATE_EVT` with `ESP_AVRC_DEINIT_SUCCESS` will be reported to the APP layer.
  *
  * @return
  *                  - ESP_OK: success
@@ -644,6 +645,10 @@ esp_err_t esp_avrc_tg_deinit(void);
  *                  passthrough commands selected to be supported according to current configuration. The
  *                  configuration can be changed using esp_avrc_tg_set_psth_cmd_filter().
  *
+ * @param[in]       filter : The type of filter to retrieve.
+ * @param[out]      cmd_set : A pointer to a bit mask that will be populated with the passthrough commands according to the filter type.
+ *                            Each bit in the mask corresponds to a specific passthrough command. This parameter should not be NULL.
+ *
  * @return
  *                  - ESP_OK: success
  *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not enabled or AVRC TG is not initialized
@@ -667,6 +672,9 @@ esp_err_t esp_avrc_tg_get_psth_cmd_filter(esp_avrc_psth_filter_t filter, esp_avr
  *
  *                  Filter type "ESP_AVRC_PSTH_FILTER_ALLOWED_CMD" does not apply to this function.
  *
+ * @param[in]       filter : The type of filter to set.
+ * @param[in]       cmd_set : A pointer to the bit mask of passthrough commands to support.
+ *
  * @return
  *                  - ESP_OK: success
  *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not enabled
@@ -707,6 +715,10 @@ bool esp_avrc_psth_bit_mask_operation(esp_avrc_bit_mask_op_t op, esp_avrc_psth_b
  *                  events selected to be supported under current configuration, The configuration can be
  *                  changed using esp_avrc_tg_set_rn_evt_cap().
  *
+ * @param[in]       cap : The type of capability to retrieve
+ * @param[out]      evt_set : A pointer to a bit mask that will store the event notification capabilities.
+ *                            Each bit in the mask corresponds to a specific event. This parameter should not be NULL.
+ *
  * @return
  *                  - ESP_OK: success
  *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not enabled or AVRC TG is not initialized
@@ -721,6 +733,9 @@ esp_err_t esp_avrc_tg_get_rn_evt_cap(esp_avrc_rn_evt_cap_t cap, esp_avrc_rn_evt_
  *                  bit mask representation in evt_set and must be a subset of allowed event IDs with current
  *                  implementation. This function should be called after esp_avrc_tg_init().
  *
+ * @param[in]       evt_set : A pointer to a bit mask representing the event notification capabilities to be set.
+ *                            Each bit in the mask corresponds to a specific event. This parameter cannot be NULL.
+ *
  * @return
  *                  - ESP_OK: success
  *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not enabled
diff --git a/components/bt/host/bluedroid/api/include/api/esp_gap_bt_api.h b/components/bt/host/bluedroid/api/include/api/esp_gap_bt_api.h
index b127552c15..09537c0a9e 100644
--- a/components/bt/host/bluedroid/api/include/api/esp_gap_bt_api.h
+++ b/components/bt/host/bluedroid/api/include/api/esp_gap_bt_api.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -38,16 +38,16 @@ typedef enum {
     ESP_BT_SET_COD_RESERVED_2      = 0x10,          /*!< overwrite the two least significant bits reserved_2 whose default value is 0b00; other values of reserved_2 are invalid according to Bluetooth Core Specification 5.4 */
 } esp_bt_cod_mode_t;
 
-#define ESP_BT_GAP_AFH_CHANNELS_LEN     10
-typedef uint8_t esp_bt_gap_afh_channels[ESP_BT_GAP_AFH_CHANNELS_LEN];
+#define ESP_BT_GAP_AFH_CHANNELS_LEN     10          /*!< length of AFH channel map in bytes */
+typedef uint8_t esp_bt_gap_afh_channels[ESP_BT_GAP_AFH_CHANNELS_LEN]; /*!< AFH channels */
 
-
-/// Discoverability and Connectability mode
+/// Connectability mode
 typedef enum {
     ESP_BT_NON_CONNECTABLE,             /*!< Non-connectable */
     ESP_BT_CONNECTABLE,                 /*!< Connectable */
 } esp_bt_connection_mode_t;
 
+/// Discoverability mode
 typedef enum {
     ESP_BT_NON_DISCOVERABLE,            /*!< Non-discoverable */
     ESP_BT_LIMITED_DISCOVERABLE,        /*!< Limited Discoverable */
@@ -75,7 +75,7 @@ typedef struct {
     void *val;                                      /*!< Device property value */
 } esp_bt_gap_dev_prop_t;
 
-/// Extended Inquiry Response data type
+/* Extended Inquiry Response data type */
 #define ESP_BT_EIR_TYPE_FLAGS                   0x01      /*!< Flag with information such as BR/EDR and LE support */
 #define ESP_BT_EIR_TYPE_INCMPL_16BITS_UUID      0x02      /*!< Incomplete list of 16-bit service UUIDs */
 #define ESP_BT_EIR_TYPE_CMPL_16BITS_UUID        0x03      /*!< Complete list of 16-bit service UUIDs */
@@ -90,46 +90,46 @@ typedef struct {
 #define ESP_BT_EIR_TYPE_MANU_SPECIFIC           0xff      /*!< Manufacturer specific data */
 #define ESP_BT_EIR_TYPE_MAX_NUM                 12        /*!< MAX number of EIR type */
 
-typedef uint8_t esp_bt_eir_type_t;
+typedef uint8_t esp_bt_eir_type_t;   /*!< EIR type */
 
 /* ACL Packet Types */
-#define ESP_BT_ACL_PKT_TYPES_MASK_DM1           0x0008
-#define ESP_BT_ACL_PKT_TYPES_MASK_DH1           0x0010
-#define ESP_BT_ACL_PKT_TYPES_MASK_DM3           0x0400
-#define ESP_BT_ACL_PKT_TYPES_MASK_DH3           0x0800
-#define ESP_BT_ACL_PKT_TYPES_MASK_DM5           0x4000
-#define ESP_BT_ACL_PKT_TYPES_MASK_DH5           0x8000
-#define ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH1      0x0002
-#define ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH1      0x0004
-#define ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH3      0x0100
-#define ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH3      0x0200
-#define ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH5      0x1000
-#define ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH5      0x2000
+#define ESP_BT_ACL_PKT_TYPES_MASK_DM1           0x0008          /*!< DM1 packet type mask */
+#define ESP_BT_ACL_PKT_TYPES_MASK_DH1           0x0010          /*!< DH1 packet type mask */
+#define ESP_BT_ACL_PKT_TYPES_MASK_DM3           0x0400          /*!< DM3 packet type mask */
+#define ESP_BT_ACL_PKT_TYPES_MASK_DH3           0x0800          /*!< DH3 packet type mask */
+#define ESP_BT_ACL_PKT_TYPES_MASK_DM5           0x4000          /*!< DM5 packet type mask */
+#define ESP_BT_ACL_PKT_TYPES_MASK_DH5           0x8000          /*!< DH5 packet type mask */
+#define ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH1      0x0002          /*!< No 2-DH1 packet type mask */
+#define ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH1      0x0004          /*!< No 3-DH1 packet type mask */
+#define ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH3      0x0100          /*!< No 2-DH3 packet type mask */
+#define ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH3      0x0200          /*!< No 3-DH3 packet type mask */
+#define ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH5      0x1000          /*!< No 2-DH5 packet type mask */
+#define ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH5      0x2000          /*!< No 3-DH5 packet type mask */
 
-// DM1 can not be disabled. All options are mandatory to include DM1.
-#define ESP_BT_ACL_DM1_ONLY     (ESP_BT_ACL_PKT_TYPES_MASK_DM1 | 0x330e)         /* 0x330e */
-#define ESP_BT_ACL_DH1_ONLY     (ESP_BT_ACL_PKT_TYPES_MASK_DH1 | 0x330e)         /* 0x331e */
-#define ESP_BT_ACL_DM3_ONLY     (ESP_BT_ACL_PKT_TYPES_MASK_DM3 | 0x330e)         /* 0x370e */
-#define ESP_BT_ACL_DH3_ONLY     (ESP_BT_ACL_PKT_TYPES_MASK_DH3 | 0x330e)         /* 0x3b0e */
-#define ESP_BT_ACL_DM5_ONLY     (ESP_BT_ACL_PKT_TYPES_MASK_DM5 | 0x330e)         /* 0x730e */
-#define ESP_BT_ACL_DH5_ONLY     (ESP_BT_ACL_PKT_TYPES_MASK_DH5 | 0x330e)         /* 0xb30e */
-#define ESP_BT_ACL_2_DH1_ONLY   (~ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH1 & 0x330e)   /* 0x330c */
-#define ESP_BT_ACL_3_DH1_ONLY   (~ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH1 & 0x330e)   /* 0x330a */
-#define ESP_BT_ACL_2_DH3_ONLY   (~ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH3 & 0x330e)   /* 0x320e */
-#define ESP_BT_ACL_3_DH3_ONLY   (~ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH3 & 0x330e)   /* 0x310e */
-#define ESP_BT_ACL_2_DH5_ONLY   (~ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH5 & 0x330e)   /* 0x230e */
-#define ESP_BT_ACL_3_DH5_ONLY   (~ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH5 & 0x330e)   /* 0x130e */
+/* DM1 can not be disabled. All options are mandatory to include DM1. */
+#define ESP_BT_ACL_DM1_ONLY     (ESP_BT_ACL_PKT_TYPES_MASK_DM1 | 0x330e)         /*!< 0x330e */
+#define ESP_BT_ACL_DH1_ONLY     (ESP_BT_ACL_PKT_TYPES_MASK_DH1 | 0x330e)         /*!< 0x331e */
+#define ESP_BT_ACL_DM3_ONLY     (ESP_BT_ACL_PKT_TYPES_MASK_DM3 | 0x330e)         /*!< 0x370e */
+#define ESP_BT_ACL_DH3_ONLY     (ESP_BT_ACL_PKT_TYPES_MASK_DH3 | 0x330e)         /*!< 0x3b0e */
+#define ESP_BT_ACL_DM5_ONLY     (ESP_BT_ACL_PKT_TYPES_MASK_DM5 | 0x330e)         /*!< 0x730e */
+#define ESP_BT_ACL_DH5_ONLY     (ESP_BT_ACL_PKT_TYPES_MASK_DH5 | 0x330e)         /*!< 0xb30e */
+#define ESP_BT_ACL_2_DH1_ONLY   (~ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH1 & 0x330e)   /*!< 0x330c */
+#define ESP_BT_ACL_3_DH1_ONLY   (~ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH1 & 0x330e)   /*!< 0x330a */
+#define ESP_BT_ACL_2_DH3_ONLY   (~ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH3 & 0x330e)   /*!< 0x320e */
+#define ESP_BT_ACL_3_DH3_ONLY   (~ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH3 & 0x330e)   /*!< 0x310e */
+#define ESP_BT_ACL_2_DH5_ONLY   (~ESP_BT_ACL_PKT_TYPES_MASK_NO_2_DH5 & 0x330e)   /*!< 0x230e */
+#define ESP_BT_ACL_3_DH5_ONLY   (~ESP_BT_ACL_PKT_TYPES_MASK_NO_3_DH5 & 0x330e)   /*!< 0x130e */
 
-typedef uint16_t esp_bt_acl_pkt_type_t;
+typedef uint16_t esp_bt_acl_pkt_type_t;     /*!< ACL packet type */
 
 /* ESP_BT_EIR_FLAG bit definition */
-#define ESP_BT_EIR_FLAG_LIMIT_DISC         (0x01 << 0)
-#define ESP_BT_EIR_FLAG_GEN_DISC           (0x01 << 1)
-#define ESP_BT_EIR_FLAG_BREDR_NOT_SPT      (0x01 << 2)
-#define ESP_BT_EIR_FLAG_DMT_CONTROLLER_SPT (0x01 << 3)
-#define ESP_BT_EIR_FLAG_DMT_HOST_SPT       (0x01 << 4)
+#define ESP_BT_EIR_FLAG_LIMIT_DISC         (0x01 << 0)    /*!< Limited discoverable flag */
+#define ESP_BT_EIR_FLAG_GEN_DISC           (0x01 << 1)    /*!< General discoverable flag */
+#define ESP_BT_EIR_FLAG_BREDR_NOT_SPT      (0x01 << 2)    /*!< BR/EDR not supported flag */
+#define ESP_BT_EIR_FLAG_DMT_CONTROLLER_SPT (0x01 << 3)    /*!< DMT controller supported flag */
+#define ESP_BT_EIR_FLAG_DMT_HOST_SPT       (0x01 << 4)    /*!< DMT host supported flag */
 
-#define ESP_BT_EIR_MAX_LEN                  240
+#define ESP_BT_EIR_MAX_LEN                  240           /*!< Maximum of EIR length */
 /// EIR data content, according to "Supplement to the Bluetooth Core Specification"
 typedef struct {
     bool                    fec_required;           /*!< FEC is required or not, true by default */
@@ -157,6 +157,7 @@ typedef enum {
     ESP_BT_COD_SRVC_INFORMATION              = 0x400,    /*!< Information, e.g., WEB-server, WAP-server */
 } esp_bt_cod_srvc_t;
 
+/// Pin type
 typedef enum{
     ESP_BT_PIN_TYPE_VARIABLE = 0,                       /*!< Refer to BTM_PIN_TYPE_VARIABLE */
     ESP_BT_PIN_TYPE_FIXED    = 1,                       /*!< Refer to BTM_PIN_TYPE_FIXED */
@@ -165,29 +166,27 @@ typedef enum{
 #define ESP_BT_PIN_CODE_LEN        16                   /*!< Max pin code length */
 typedef uint8_t esp_bt_pin_code_t[ESP_BT_PIN_CODE_LEN]; /*!< Pin Code (upto 128 bits) MSB is 0 */
 
+/// SP parameter type
 typedef enum {
     ESP_BT_SP_IOCAP_MODE = 0,                            /*!< Set IO mode */
     //ESP_BT_SP_OOB_DATA, //TODO                         /*!< Set OOB data */
 } esp_bt_sp_param_t;
 
-/* relate to BTM_IO_CAP_xxx in stack/btm_api.h */
-#define ESP_BT_IO_CAP_OUT                      0        /*!< DisplayOnly */         /* relate to BTM_IO_CAP_OUT in stack/btm_api.h */
-#define ESP_BT_IO_CAP_IO                       1        /*!< DisplayYesNo */        /* relate to BTM_IO_CAP_IO in stack/btm_api.h */
-#define ESP_BT_IO_CAP_IN                       2        /*!< KeyboardOnly */        /* relate to BTM_IO_CAP_IN in stack/btm_api.h */
-#define ESP_BT_IO_CAP_NONE                     3        /*!< NoInputNoOutput */     /* relate to BTM_IO_CAP_NONE in stack/btm_api.h */
+/* Input/Output capabilities */
+#define ESP_BT_IO_CAP_OUT                      0        /*!< DisplayOnly */
+#define ESP_BT_IO_CAP_IO                       1        /*!< DisplayYesNo */
+#define ESP_BT_IO_CAP_IN                       2        /*!< KeyboardOnly */
+#define ESP_BT_IO_CAP_NONE                     3        /*!< NoInputNoOutput */
 typedef uint8_t esp_bt_io_cap_t;                        /*!< Combination of the IO Capability */
 
-
-/* BTM Power manager modes */
+/* BT Power manager modes */
 #define ESP_BT_PM_MD_ACTIVE                 0x00        /*!< Active mode */
 #define ESP_BT_PM_MD_HOLD                   0x01        /*!< Hold mode */
 #define ESP_BT_PM_MD_SNIFF                  0x02        /*!< Sniff mode */
 #define ESP_BT_PM_MD_PARK                   0x03        /*!< Park state */
-typedef uint8_t esp_bt_pm_mode_t;
+typedef uint8_t esp_bt_pm_mode_t;                       /*!< BT Power manager mode type */
 
-
-
-/// Bits of major service class field
+/* Bits of major service class field */
 #define ESP_BT_COD_SRVC_BIT_MASK              (0xffe000) /*!< Major service bit mask */
 #define ESP_BT_COD_SRVC_BIT_OFFSET            (13)       /*!< Major service bit offset */
 
@@ -195,9 +194,9 @@ typedef uint8_t esp_bt_pm_mode_t;
 typedef enum {
     ESP_BT_COD_MAJOR_DEV_MISC                = 0,    /*!< Miscellaneous */
     ESP_BT_COD_MAJOR_DEV_COMPUTER            = 1,    /*!< Computer */
-    ESP_BT_COD_MAJOR_DEV_PHONE               = 2,    /*!< Phone(cellular, cordless, pay phone, modem */
+    ESP_BT_COD_MAJOR_DEV_PHONE               = 2,    /*!< Phone (cellular, cordless, pay phone, modem) */
     ESP_BT_COD_MAJOR_DEV_LAN_NAP             = 3,    /*!< LAN, Network Access Point */
-    ESP_BT_COD_MAJOR_DEV_AV                  = 4,    /*!< Audio/Video(headset, speaker, stereo, video display, VCR */
+    ESP_BT_COD_MAJOR_DEV_AV                  = 4,    /*!< Audio/Video (headset, speaker, stereo, video display, VCR) */
     ESP_BT_COD_MAJOR_DEV_PERIPHERAL          = 5,    /*!< Peripheral(mouse, joystick, keyboard) */
     ESP_BT_COD_MAJOR_DEV_IMAGING             = 6,    /*!< Imaging(printer, scanner, camera, display */
     ESP_BT_COD_MAJOR_DEV_WEARABLE            = 7,    /*!< Wearable */
@@ -228,20 +227,19 @@ typedef enum {
     ESP_BT_COD_MINOR_PERIPHERAL_HAND_GESTURAL_INPUT = 0x09, /*!< Hand Gestural Input */
 } esp_bt_cod_minor_peripheral_t;
 
-/// Bits of major device class field
+/* Bits of major device class field */
 #define ESP_BT_COD_MAJOR_DEV_BIT_MASK         (0x1f00) /*!< Major device bit mask */
 #define ESP_BT_COD_MAJOR_DEV_BIT_OFFSET       (8)      /*!< Major device bit offset */
 
-/// Bits of minor device class field
+/* Bits of minor device class field */
 #define ESP_BT_COD_MINOR_DEV_BIT_MASK         (0xfc)   /*!< Minor device bit mask */
 #define ESP_BT_COD_MINOR_DEV_BIT_OFFSET       (2)      /*!< Minor device bit offset */
 
-/// Bits of format type
+/* Bits of format type */
 #define ESP_BT_COD_FORMAT_TYPE_BIT_MASK       (0x03)   /*!< Format type bit mask */
 #define ESP_BT_COD_FORMAT_TYPE_BIT_OFFSET     (0)      /*!< Format type bit offset */
 
-/// Class of device format type 1
-#define ESP_BT_COD_FORMAT_TYPE_1              (0x00)
+#define ESP_BT_COD_FORMAT_TYPE_1              (0x00)   /*!< Class of device format type 1 */
 
 /** Bluetooth Device Discovery state */
 typedef enum {
@@ -249,7 +247,7 @@ typedef enum {
     ESP_BT_GAP_DISCOVERY_STARTED,                   /*!< Device discovery started */
 } esp_bt_gap_discovery_state_t;
 
-/// Type of link key
+/* Type of link key */
 #define ESP_BT_LINK_KEY_COMB                (0x00)  /*!< Combination Key */
 #define ESP_BT_LINK_KEY_DBG_COMB            (0x03)  /*!< Debug Combination Key */
 #define ESP_BT_LINK_KEY_UNAUTHED_COMB_P192  (0x04)  /*!< Unauthenticated Combination Key generated from P-192 */
@@ -257,13 +255,13 @@ typedef enum {
 #define ESP_BT_LINK_KEY_CHG_COMB            (0x06)  /*!< Changed Combination Key */
 #define ESP_BT_LINK_KEY_UNAUTHED_COMB_P256  (0x07)  /*!< Unauthenticated Combination Key generated from P-256 */
 #define ESP_BT_LINK_KEY_AUTHED_COMB_P256    (0x08)  /*!< Authenticated Combination Key generated from P-256 */
-typedef uint8_t esp_bt_link_key_type_t;
+typedef uint8_t esp_bt_link_key_type_t;             /*!< Link key type */
 
-/// Type of encryption
+/* Type of encryption */
 #define ESP_BT_ENC_MODE_OFF                 (0x00)  /*!< Link Level Encryption is OFF */
 #define ESP_BT_ENC_MODE_E0                  (0x01)  /*!< Link Level Encryption is ON with E0 */
 #define ESP_BT_ENC_MODE_AES                 (0x02)  /*!< Link Level Encryption is ON with AES-CCM */
-typedef uint8_t esp_bt_enc_mode_t;
+typedef uint8_t esp_bt_enc_mode_t;                  /*!< encryption mode type */
 
 /// BT GAP callback events
 typedef enum {
@@ -280,7 +278,7 @@ typedef enum {
     ESP_BT_GAP_CONFIG_EIR_DATA_EVT,                 /*!< Config EIR data event */
     ESP_BT_GAP_SET_AFH_CHANNELS_EVT,                /*!< Set AFH channels event */
     ESP_BT_GAP_READ_REMOTE_NAME_EVT,                /*!< Read Remote Name event */
-    ESP_BT_GAP_MODE_CHG_EVT,
+    ESP_BT_GAP_MODE_CHG_EVT,                     /*!< Mode change event */
     ESP_BT_GAP_REMOVE_BOND_DEV_COMPLETE_EVT,         /*!< remove bond device complete event */
     ESP_BT_GAP_QOS_CMPL_EVT,                        /*!< QOS complete event */
     ESP_BT_GAP_ACL_CONN_CMPL_STAT_EVT,              /*!< ACL connection complete status event */
@@ -299,11 +297,11 @@ typedef enum {
     ESP_BT_INQ_MODE_LIMITED_INQUIRY,                /*!< Limited inquiry mode */
 } esp_bt_inq_mode_t;
 
-/** Minimum and Maximum inquiry length*/
+/* Minimum and Maximum inquiry length */
 #define ESP_BT_GAP_MIN_INQ_LEN                (0x01)  /*!< Minimum inquiry duration, unit is 1.28s */
 #define ESP_BT_GAP_MAX_INQ_LEN                (0x30)  /*!< Maximum inquiry duration, unit is 1.28s */
 
-/** Minimum, Default and Maximum poll interval **/
+/* Minimum, Default and Maximum poll interval */
 #define ESP_BT_GAP_TPOLL_MIN                  (0x0006) /*!< Minimum poll interval, unit is 625 microseconds */
 #define ESP_BT_GAP_TPOLL_DFT                  (0x0028) /*!< Default poll interval, unit is 625 microseconds */
 #define ESP_BT_GAP_TPOLL_MAX                  (0x1000) /*!< Maximum poll interval, unit is 625 microseconds */
@@ -353,7 +351,7 @@ typedef union {
     } rmt_srvc_rec;                            /*!< specific service record from remote device parameter struct */
 
     /**
-     * @brief ESP_BT_GAP_READ_RSSI_DELTA_EVT *
+     * @brief ESP_BT_GAP_READ_RSSI_DELTA_EVT
      */
     struct read_rssi_delta_param {
         esp_bd_addr_t bda;                     /*!< remote bluetooth device address*/
@@ -362,7 +360,7 @@ typedef union {
     } read_rssi_delta;                         /*!< read rssi parameter struct */
 
     /**
-     * @brief ESP_BT_GAP_CONFIG_EIR_DATA_EVT *
+     * @brief ESP_BT_GAP_CONFIG_EIR_DATA_EVT
      */
     struct config_eir_data_param {
         esp_bt_status_t stat;                                   /*!< config EIR status:
@@ -597,6 +595,8 @@ static inline bool esp_bt_gap_is_valid_cod(uint32_t cod)
 /**
  * @brief           register callback function. This function should be called after esp_bluedroid_enable() completes successfully
  *
+ * @param[in]       callback : callback function
+ *
  * @return
  *                  - ESP_OK : Succeed
  *                  - ESP_FAIL: others
@@ -656,6 +656,8 @@ esp_err_t esp_bt_gap_cancel_discovery(void);
  * @brief           Start SDP to get remote services. This function should be called after esp_bluedroid_enable() completes successfully.
  *                  esp_bt_gap_cb_t will be called with ESP_BT_GAP_RMT_SRVCS_EVT after service discovery ends.
  *
+ * @param[in]       remote_bda : remote bluetooth device address
+ *
  * @return
  *                  - ESP_OK : Succeed
  *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
@@ -668,6 +670,10 @@ esp_err_t esp_bt_gap_get_remote_services(esp_bd_addr_t remote_bda);
  *                  esp_bluedroid_enable() completes successfully.
  *
  *                  esp_bt_gap_cb_t will be called with ESP_BT_GAP_RMT_SRVC_REC_EVT after service discovery ends
+ *
+ * @param[in]       remote_bda : remote bluetooth device address
+ * @param[in]       uuid : uuid
+ *
  * @return
  *                  - ESP_OK : Succeed
  *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
@@ -944,6 +950,9 @@ esp_err_t esp_bt_gap_get_page_timeout(void);
  *                  An ESP_BT_GAP_SET_ACL_PPKT_TYPES_EVT event will reported to
  *                  the APP layer.
  *
+ * @param[in]       remote_bda : remote bluetooth device address
+ * @param[in]       pkt_types : packet type
+ *
  * @return          - ESP_OK: success
  *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
  *                  - other: failed
diff --git a/components/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h b/components/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h
index 885a2b4418..a2f34e1c63 100644
--- a/components/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h
+++ b/components/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h
@@ -16,29 +16,29 @@ extern "C" {
 #endif
 
 /* features masks of HF AG  */
-#define ESP_HF_PEER_FEAT_3WAY       0x01        /* Three-way calling */
-#define ESP_HF_PEER_FEAT_ECNR       0x02        /* Echo cancellation and/or noise reduction */
-#define ESP_HF_PEER_FEAT_VREC       0x04        /* Voice recognition */
-#define ESP_HF_PEER_FEAT_INBAND     0x08        /* In-band ring tone */
-#define ESP_HF_PEER_FEAT_VTAG       0x10        /* Attach a phone number to a voice tag */
-#define ESP_HF_PEER_FEAT_REJECT     0x20        /* Ability to reject incoming call */
-#define ESP_HF_PEER_FEAT_ECS        0x40        /* Enhanced Call Status */
-#define ESP_HF_PEER_FEAT_ECC        0x80        /* Enhanced Call Control */
-#define ESP_HF_PEER_FEAT_EXTERR    0x100        /* Extended error codes */
-#define ESP_HF_PEER_FEAT_CODEC     0x200        /* Codec Negotiation */
+#define ESP_HF_PEER_FEAT_3WAY       0x01        /*!< Three-way calling */
+#define ESP_HF_PEER_FEAT_ECNR       0x02        /*!< Echo cancellation and/or noise reduction */
+#define ESP_HF_PEER_FEAT_VREC       0x04        /*!< Voice recognition */
+#define ESP_HF_PEER_FEAT_INBAND     0x08        /*!< In-band ring tone */
+#define ESP_HF_PEER_FEAT_VTAG       0x10        /*!< Attach a phone number to a voice tag */
+#define ESP_HF_PEER_FEAT_REJECT     0x20        /*!< Ability to reject incoming call */
+#define ESP_HF_PEER_FEAT_ECS        0x40        /*!< Enhanced Call Status */
+#define ESP_HF_PEER_FEAT_ECC        0x80        /*!< Enhanced Call Control */
+#define ESP_HF_PEER_FEAT_EXTERR    0x100        /*!< Extended error codes */
+#define ESP_HF_PEER_FEAT_CODEC     0x200        /*!< Codec Negotiation */
 /* HFP 1.7+ */
-#define ESP_HF_PEER_FEAT_HF_IND    0x400        /* HF Indicators */
-#define ESP_HF_PEER_FEAT_ESCO_S4   0x800        /* eSCO S4 Setting Supported */
+#define ESP_HF_PEER_FEAT_HF_IND    0x400        /*!< HF Indicators */
+#define ESP_HF_PEER_FEAT_ESCO_S4   0x800        /*!< eSCO S4 Setting Supported */
 
 
 /* CHLD feature masks of HF AG */
-#define ESP_HF_CHLD_FEAT_REL           0x01       /* 0  Release waiting call or held calls */
-#define ESP_HF_CHLD_FEAT_REL_ACC       0x02       /* 1  Release active calls and accept other waiting or held call */
-#define ESP_HF_CHLD_FEAT_REL_X         0x04       /* 1x Release specified active call only */
-#define ESP_HF_CHLD_FEAT_HOLD_ACC      0x08       /* 2  Active calls on hold and accept other waiting or held call */
-#define ESP_HF_CHLD_FEAT_PRIV_X        0x10       /* 2x Request private mode with specified call(put the rest on hold) */
-#define ESP_HF_CHLD_FEAT_MERGE         0x20       /* 3  Add held call to multiparty */
-#define ESP_HF_CHLD_FEAT_MERGE_DETACH  0x40       /* 4  Connect two calls and leave(disconnect from multiparty) */
+#define ESP_HF_CHLD_FEAT_REL           0x01       /*!< 0  Release waiting call or held calls */
+#define ESP_HF_CHLD_FEAT_REL_ACC       0x02       /*!< 1  Release active calls and accept other waiting or held call */
+#define ESP_HF_CHLD_FEAT_REL_X         0x04       /*!< 1x Release specified active call only */
+#define ESP_HF_CHLD_FEAT_HOLD_ACC      0x08       /*!< 2  Active calls on hold and accept other waiting or held call */
+#define ESP_HF_CHLD_FEAT_PRIV_X        0x10       /*!< 2x Request private mode with specified call(put the rest on hold) */
+#define ESP_HF_CHLD_FEAT_MERGE         0x20       /*!< 3  Add held call to multiparty */
+#define ESP_HF_CHLD_FEAT_MERGE_DETACH  0x40       /*!< 4  Connect two calls and leave(disconnect from multiparty) */
 
 /// HF callback events
 typedef enum
@@ -59,7 +59,7 @@ typedef enum
 
     ESP_HF_ATA_RESPONSE_EVT,                  /*!< Answer an Incoming Call */
     ESP_HF_CHUP_RESPONSE_EVT,                 /*!< Reject an Incoming Call */
-    ESP_HF_DIAL_EVT,                          /*!< Origin an outgoing call with specific number or the dial the last number */
+    ESP_HF_DIAL_EVT,                          /*!< Originate an outgoing call with specific number or dial the last number */
     ESP_HF_WBS_RESPONSE_EVT,                  /*!< Codec Status */
     ESP_HF_BCS_RESPONSE_EVT,                  /*!< Final Codec Choice */
     ESP_HF_PKT_STAT_NUMS_GET_EVT,             /*!< Request number of packet different status */
@@ -89,7 +89,7 @@ typedef union
      * @brief  ESP_HF_CONNECTION_STATE_EVT
      */
     struct hf_conn_stat_param {
-        esp_bd_addr_t remote_bda;                 /*!< Remote bluetooth device address */
+        esp_bd_addr_t remote_bda;                 /*!< Remote Bluetooth device address */
         esp_hf_connection_state_t state;          /*!< Connection state */
         uint32_t peer_feat;                       /*!< HF supported features */
         uint32_t chld_feat;                       /*!< AG supported features on call hold and multiparty services */
@@ -226,10 +226,10 @@ typedef union
         uint32_t rx_total;        /*!< the total number of packets received */
         uint32_t rx_correct;      /*!< the total number of packets data correctly received */
         uint32_t rx_err;          /*!< the total number of packets data with possible invalid */
-        uint32_t rx_none;         /*!< the total number of packets data no received */
+        uint32_t rx_none;         /*!< the total number of packets data not received */
         uint32_t rx_lost;         /*!< the total number of packets data partially lost */
-        uint32_t tx_total;        /*!< the total number of packets send */
-        uint32_t tx_discarded;    /*!< the total number of packets send lost */
+        uint32_t tx_total;        /*!< the total number of packets sent */
+        uint32_t tx_discarded;    /*!< the total number of packets sent and lost */
     } pkt_nums;                   /*!< AG callback param of ESP_HF_PKT_STAT_NUMS_GET_EVT */
 
     /**
@@ -273,9 +273,9 @@ typedef uint32_t (* esp_hf_outgoing_data_cb_t) (uint8_t *buf, uint32_t len);
 /**
  * @brief           HF AG callback function type
  *
- * @param           event : Event type
+ * @param[in]       event : Event type
  *
- * @param           param : Pointer to callback parameter
+ * @param[in]       param : Pointer to callback parameter
  */
 typedef void (* esp_hf_cb_t) (esp_hf_cb_event_t event, esp_hf_cb_param_t *param);
 
diff --git a/components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h b/components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h
index a373dc5c74..a61372793d 100644
--- a/components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h
+++ b/components/bt/host/bluedroid/api/include/api/esp_hf_client_api.h
@@ -15,9 +15,9 @@
 extern "C" {
 #endif
 
-#define ESP_BT_HF_CLIENT_NUMBER_LEN           (32)
-#define ESP_BT_HF_CLIENT_OPERATOR_NAME_LEN    (16)
-#define ESP_BT_HF_AT_SEND_XAPL_LEN            (14)
+#define ESP_BT_HF_CLIENT_NUMBER_LEN           (32)   /*!< Maximum length of the phone number string in HFP Client */
+#define ESP_BT_HF_CLIENT_OPERATOR_NAME_LEN    (16)   /*!< Maximum length of the operator name string in HFP Client */
+#define ESP_BT_HF_AT_SEND_XAPL_LEN            (14)   /*!< Length of the XAPL string in AT command for HFP Client */
 
 /// Bluetooth HFP RFCOMM connection and service level connection status
 typedef enum {
@@ -25,7 +25,7 @@ typedef enum {
     ESP_HF_CLIENT_CONNECTION_STATE_CONNECTING,           /*!< connecting remote device on the RFCOMM data link*/
     ESP_HF_CLIENT_CONNECTION_STATE_CONNECTED,            /*!< RFCOMM connection established */
     ESP_HF_CLIENT_CONNECTION_STATE_SLC_CONNECTED,        /*!< service level connection established */
-    ESP_HF_CLIENT_CONNECTION_STATE_DISCONNECTING,        /*!< disconnecting with remote device on the RFCOMM dat link*/
+    ESP_HF_CLIENT_CONNECTION_STATE_DISCONNECTING,        /*!< disconnecting with remote device on the RFCOMM data link*/
 } esp_hf_client_connection_state_t;
 
 /// Bluetooth HFP audio connection status
@@ -52,35 +52,35 @@ typedef struct {
 } esp_hf_client_profile_status_t;
 
 /* features masks of AG */
-#define ESP_HF_CLIENT_PEER_FEAT_3WAY       0x01        /* Three-way calling */
-#define ESP_HF_CLIENT_PEER_FEAT_ECNR       0x02        /* Echo cancellation and/or noise reduction */
-#define ESP_HF_CLIENT_PEER_FEAT_VREC       0x04        /* Voice recognition */
-#define ESP_HF_CLIENT_PEER_FEAT_INBAND     0x08        /* In-band ring tone */
-#define ESP_HF_CLIENT_PEER_FEAT_VTAG       0x10        /* Attach a phone number to a voice tag */
-#define ESP_HF_CLIENT_PEER_FEAT_REJECT     0x20        /* Ability to reject incoming call */
-#define ESP_HF_CLIENT_PEER_FEAT_ECS        0x40        /* Enhanced Call Status */
-#define ESP_HF_CLIENT_PEER_FEAT_ECC        0x80        /* Enhanced Call Control */
-#define ESP_HF_CLIENT_PEER_FEAT_EXTERR    0x100        /* Extended error codes */
-#define ESP_HF_CLIENT_PEER_FEAT_CODEC     0x200        /* Codec Negotiation */
+#define ESP_HF_CLIENT_PEER_FEAT_3WAY       0x01        /*!< Three-way calling */
+#define ESP_HF_CLIENT_PEER_FEAT_ECNR       0x02        /*!< Echo cancellation and/or noise reduction */
+#define ESP_HF_CLIENT_PEER_FEAT_VREC       0x04        /*!< Voice recognition */
+#define ESP_HF_CLIENT_PEER_FEAT_INBAND     0x08        /*!< In-band ring tone */
+#define ESP_HF_CLIENT_PEER_FEAT_VTAG       0x10        /*!< Attach a phone number to a voice tag */
+#define ESP_HF_CLIENT_PEER_FEAT_REJECT     0x20        /*!< Ability to reject incoming call */
+#define ESP_HF_CLIENT_PEER_FEAT_ECS        0x40        /*!< Enhanced Call Status */
+#define ESP_HF_CLIENT_PEER_FEAT_ECC        0x80        /*!< Enhanced Call Control */
+#define ESP_HF_CLIENT_PEER_FEAT_EXTERR    0x100        /*!< Extended error codes */
+#define ESP_HF_CLIENT_PEER_FEAT_CODEC     0x200        /*!< Codec Negotiation */
 /* HFP 1.7+ */
-#define ESP_HF_CLIENT_PEER_FEAT_HF_IND    0x400        /* HF Indicators */
-#define ESP_HF_CLIENT_PEER_FEAT_ESCO_S4   0x800        /* eSCO S4 Setting Supported */
+#define ESP_HF_CLIENT_PEER_FEAT_HF_IND    0x400        /*!< HF Indicators */
+#define ESP_HF_CLIENT_PEER_FEAT_ESCO_S4   0x800        /*!< eSCO S4 Setting Supported */
 
 /* CHLD feature masks of AG */
-#define ESP_HF_CLIENT_CHLD_FEAT_REL           0x01       /* 0  Release waiting call or held calls */
-#define ESP_HF_CLIENT_CHLD_FEAT_REL_ACC       0x02       /* 1  Release active calls and accept other waiting or held call */
-#define ESP_HF_CLIENT_CHLD_FEAT_REL_X         0x04       /* 1x Release specified active call only */
-#define ESP_HF_CLIENT_CHLD_FEAT_HOLD_ACC      0x08       /* 2  Active calls on hold and accept other waiting or held call */
-#define ESP_HF_CLIENT_CHLD_FEAT_PRIV_X        0x10       /* 2x Request private mode with specified call(put the rest on hold) */
-#define ESP_HF_CLIENT_CHLD_FEAT_MERGE         0x20       /* 3  Add held call to multiparty */
-#define ESP_HF_CLIENT_CHLD_FEAT_MERGE_DETACH  0x40       /* 4  Connect two calls and leave(disconnect from multiparty) */
+#define ESP_HF_CLIENT_CHLD_FEAT_REL           0x01       /*!< 0  Release waiting call or held calls */
+#define ESP_HF_CLIENT_CHLD_FEAT_REL_ACC       0x02       /*!< 1  Release active calls and accept other waiting or held call */
+#define ESP_HF_CLIENT_CHLD_FEAT_REL_X         0x04       /*!< 1x Release specified active call only */
+#define ESP_HF_CLIENT_CHLD_FEAT_HOLD_ACC      0x08       /*!< 2  Active calls on hold and accept other waiting or held call */
+#define ESP_HF_CLIENT_CHLD_FEAT_PRIV_X        0x10       /*!< 2x Request private mode with specified call(put the rest on hold) */
+#define ESP_HF_CLIENT_CHLD_FEAT_MERGE         0x20       /*!< 3  Add held call to multiparty */
+#define ESP_HF_CLIENT_CHLD_FEAT_MERGE_DETACH  0x40       /*!< 4  Connect two calls and leave(disconnect from multiparty) */
 
 /* XAPL feature masks*/
-#define ESP_HF_CLIENT_XAPL_FEAT_RESERVED            0x01    /* reserved */
-#define ESP_HF_CLIENT_XAPL_FEAT_BATTERY_REPORT      0x02    /* The accessory supports battery reporting (reserved only for battery operated accessories) */
-#define ESP_HF_CLIENT_XAPL_FEAT_DOCKED              0x04    /* The accessory is docked or powered (reserved only for battery operated accessories). */
-#define ESP_HF_CLIENT_XAPL_FEAT_SIRI_STATUS_REPORT  0x08    /* The accessory supports Siri status reporting */
-#define ESP_HF_CLIENT_XAPL_NR_STATUS_REPORT         0x10    /* the accessory supports noise reduction (NR) status reporting */
+#define ESP_HF_CLIENT_XAPL_FEAT_RESERVED            0x01    /*!< reserved */
+#define ESP_HF_CLIENT_XAPL_FEAT_BATTERY_REPORT      0x02    /*!< The accessory supports battery reporting (reserved only for battery operated accessories) */
+#define ESP_HF_CLIENT_XAPL_FEAT_DOCKED              0x04    /*!< The accessory is docked or powered (reserved only for battery operated accessories). */
+#define ESP_HF_CLIENT_XAPL_FEAT_SIRI_STATUS_REPORT  0x08    /*!< The accessory supports Siri status reporting */
+#define ESP_HF_CLIENT_XAPL_NR_STATUS_REPORT         0x10    /*!< The accessory supports noise reduction (NR) status reporting */
 
 /// HF CLIENT callback events
 typedef enum {
@@ -184,7 +184,7 @@ typedef union {
      */
     struct hf_client_call_setup_ind_param {
         esp_hf_call_setup_status_t status;       /*!< call setup status indicator */
-    } call_setup;                                /*!< HF callback param of ESP_HF_CLIENT_BVRA_EVT */
+    } call_setup;                                /*!< HF callback param of `ESP_HF_CLIENT_CIND_CALL_SETUP_EVT` */
 
     /**
      * @brief ESP_HF_CLIENT_CIND_CALL_HELD_EVT
@@ -198,7 +198,7 @@ typedef union {
      */
     struct hf_client_btrh_param {
         esp_hf_btrh_status_t status;             /*!< call hold and response status result code */
-    } btrh;                                      /*!< HF callback param of ESP_HF_CLIENT_BRTH_EVT */
+    } btrh;                                      /*!< HF callback param of ESP_HF_CLIENT_BTRH_EVT */
 
     /**
      * @brief ESP_HF_CLIENT_CLIP_EVT
@@ -212,7 +212,7 @@ typedef union {
      */
     struct hf_client_ccwa_param {
         const char *number;                      /*!< phone number string of waiting call */
-    } ccwa;                                      /*!< HF callback param of ESP_HF_CLIENT_BVRA_EVT */
+    } ccwa;                                      /*!< HF callback param of ESP_HF_CLIENT_CCWA_EVT */
 
     /**
      * @brief ESP_HF_CLIENT_CLCC_EVT
@@ -316,9 +316,9 @@ typedef uint32_t (* esp_hf_client_outgoing_data_cb_t)(uint8_t *buf, uint32_t len
 /**
  * @brief           HFP client callback function type
  *
- * @param           event : Event type
+ * @param[in]       event : Event type
  *
- * @param           param : Pointer to callback parameter
+ * @param[in]       param : Pointer to callback parameter
  */
 typedef void (* esp_hf_client_cb_t)(esp_hf_client_cb_event_t event, esp_hf_client_cb_param_t *param);
 
@@ -611,7 +611,7 @@ esp_err_t esp_hf_client_send_dtmf(char code);
  *
  * @brief           Send command to enable Vendor specific feature to indicate battery level
  *                  and docker status
- *                  This is Apple-specific commands, but used by most device, including Android and Windows
+ *                  This is an Apple-specific command, but used by most devices, including Android and Windows
  *
  * @param[in]       information: XAPL vendorID-productID-version, such as "0505-1995-0610"
  *                               vendorID: A string representation of the hex value of the vendor ID from the manufacturer, without the 0x prefix.
diff --git a/components/bt/host/bluedroid/api/include/api/esp_hf_defs.h b/components/bt/host/bluedroid/api/include/api/esp_hf_defs.h
index ec41b8641a..f6595cd880 100644
--- a/components/bt/host/bluedroid/api/include/api/esp_hf_defs.h
+++ b/components/bt/host/bluedroid/api/include/api/esp_hf_defs.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -25,8 +25,8 @@ typedef enum {
 
 /// in-band ring tone state
 typedef enum {
-    ESP_HF_IN_BAND_RINGTONE_NOT_PROVIDED = 0,
-    ESP_HF_IN_BAND_RINGTONE_PROVIDED,
+    ESP_HF_IN_BAND_RINGTONE_NOT_PROVIDED = 0,   /*!< Indicates that the in-band ringtone is not provided by the Hands-Free device */
+    ESP_HF_IN_BAND_RINGTONE_PROVIDED,           /*!< Indicates that the in-band ringtone is provided by the Hands-Free device */
 } esp_hf_in_band_ring_state_t;
 
 /// voice recognition state
@@ -49,16 +49,17 @@ typedef enum {
     ESP_HF_AUDIO_STATE_CONNECTED_MSBC,            /*!< mSBC audio connection is established */
 } esp_hf_audio_state_t;
 
+/// Bluetooth HFP audio volume type
 typedef enum {
-    ESP_HF_VOLUME_TYPE_SPK = 0,
-    ESP_HF_VOLUME_TYPE_MIC
+    ESP_HF_VOLUME_TYPE_SPK = 0,                 /*!< speaker */
+    ESP_HF_VOLUME_TYPE_MIC                      /*!< microphone */
 } esp_hf_volume_type_t;
 
 /// +CIND network service availability status
 typedef enum
 {
-    ESP_HF_NETWORK_STATE_NOT_AVAILABLE = 0,
-    ESP_HF_NETWORK_STATE_AVAILABLE
+    ESP_HF_NETWORK_STATE_NOT_AVAILABLE = 0,         /*!< Indicates that the network service is not available */
+    ESP_HF_NETWORK_STATE_AVAILABLE                  /*!< Indicates that the network service is available */
 } esp_hf_network_state_t;
 
 /// +CIEV report type
@@ -75,8 +76,8 @@ typedef enum {
 /** +CIEV Service type */
 typedef enum
 {
-    ESP_HF_SERVICE_TYPE_HOME = 0,
-    ESP_HF_SERVICE_TYPE_ROAMING
+    ESP_HF_SERVICE_TYPE_HOME = 0,       /*!< Indicates the service is in the home */
+    ESP_HF_SERVICE_TYPE_ROAMING         /*!< Indicates the service is in roaming */
 } esp_hf_service_type_t;
 
 /// +CIND call status indicator values
@@ -131,9 +132,9 @@ typedef enum {
 
 /// +CLCC call mode
 typedef enum {
-    ESP_HF_CURRENT_CALL_MODE_VOICE = 0,
-    ESP_HF_CURRENT_CALL_MODE_DATA = 1,
-    ESP_HF_CURRENT_CALL_MODE_FAX = 2,
+    ESP_HF_CURRENT_CALL_MODE_VOICE = 0,             /*!< the current call is a voice call */
+    ESP_HF_CURRENT_CALL_MODE_DATA = 1,              /*!< the current call is a data call */
+    ESP_HF_CURRENT_CALL_MODE_FAX = 2,               /*!< the current call is a fax call */
 } esp_hf_current_call_mode_t;
 
 /// +CLCC address type
@@ -166,22 +167,22 @@ typedef enum {
 /* +NREC */
 typedef enum
 {
-    ESP_HF_NREC_STOP = 0,
-    ESP_HF_NREC_START
+    ESP_HF_NREC_STOP = 0,           /*!< Stop the NREC */
+    ESP_HF_NREC_START               /*!< Start the NREC */
 } esp_hf_nrec_t;
 
 ///+CCWA response status
 typedef enum {
-    ESP_HF_CALL_WAITING_INACTIVE,
-    ESP_HF_CALL_WAITING_ACTIVE,
+    ESP_HF_CALL_WAITING_INACTIVE,       /*!< inactive call waiting */
+    ESP_HF_CALL_WAITING_ACTIVE,         /*!< active call waiting */
 } esp_hf_call_waiting_status_t;
 
 /* WBS codec setting */
 typedef enum
 {
-   ESP_HF_WBS_NONE,
-   ESP_HF_WBS_NO,
-   ESP_HF_WBS_YES
+   ESP_HF_WBS_NONE,         /*!< No Wideband Speech (WBS) codec support */
+   ESP_HF_WBS_NO,           /*!< Wideband Speech (WBS) codec is not enabled */
+   ESP_HF_WBS_YES           /*!< Wideband Speech (WBS) codec is enabled */
 }esp_hf_wbs_config_t;
 
 /// Bluetooth HFP RFCOMM connection and service level connection status
@@ -196,11 +197,11 @@ typedef enum {
 /// AT+CHLD command values
 typedef enum {
     ESP_HF_CHLD_TYPE_REL = 0,               /*!< <0>, Terminate all held or set UDUB("busy") to a waiting call */
-    ESP_HF_CHLD_TYPE_REL_ACC,               /*!< <1>, Terminate all active calls and accepts a waiting/held call */
-    ESP_HF_CHLD_TYPE_HOLD_ACC,              /*!< <2>, Hold all active calls and accepts a waiting/held call */
+    ESP_HF_CHLD_TYPE_REL_ACC,               /*!< <1>, Terminate all active calls and accept a waiting/held call */
+    ESP_HF_CHLD_TYPE_HOLD_ACC,              /*!< <2>, Hold all active calls and accept a waiting/held call */
     ESP_HF_CHLD_TYPE_MERGE,                 /*!< <3>, Add all held calls to a conference */
-    ESP_HF_CHLD_TYPE_MERGE_DETACH,          /*!< <4>, connect the two calls and disconnects the subscriber from both calls */
-    ESP_HF_CHLD_TYPE_REL_X,                 /*!< <1x>, releases specified calls only */
+    ESP_HF_CHLD_TYPE_MERGE_DETACH,          /*!< <4>, connect the two calls and disconnect the subscriber from both calls */
+    ESP_HF_CHLD_TYPE_REL_X,                 /*!< <1x>, release specified calls only */
     ESP_HF_CHLD_TYPE_PRIV_X,                /*!< <2x>, request private consultation mode with specified call */
 } esp_hf_chld_type_t;
 
@@ -218,8 +219,8 @@ typedef enum {
 
 /* AT response code - OK/Error */
 typedef enum {
-    ESP_HF_AT_RESPONSE_ERROR = 0,
-    ESP_HF_AT_RESPONSE_OK
+    ESP_HF_AT_RESPONSE_ERROR = 0,       /*!< error in the AT command response */
+    ESP_HF_AT_RESPONSE_OK               /*!< successful AT command response */
 } esp_hf_at_response_t;
 
 /// Extended Audio Gateway Error Result Code Response
@@ -240,7 +241,7 @@ typedef enum {
     ESP_HF_CME_MEMORY_FULL = 20,                  /*!< memory full */
     ESP_HF_CME_INVALID_INDEX = 21,                /*!< invalid index */
     ESP_HF_CME_MEMORY_FAILURE = 23,              /*!< memory failure */
-    ESP_HF_CME_TEXT_STRING_TOO_LONG = 24,         /*!< test string too long */
+    ESP_HF_CME_TEXT_STRING_TOO_LONG = 24,         /*!< text string too long */
     ESP_HF_CME_INVALID_CHARACTERS_IN_TEXT_STRING = 25,  /*!< invalid characters in text string */
     ESP_HF_CME_DIAL_STRING_TOO_LONG = 26,         /*!< dial string too long*/
     ESP_HF_CME_INVALID_CHARACTERS_IN_DIAL_STRING = 27,  /*!< invalid characters in dial string */
diff --git a/components/bt/host/bluedroid/api/include/api/esp_hidd_api.h b/components/bt/host/bluedroid/api/include/api/esp_hidd_api.h
index f16bbcb0fa..2348e752d5 100644
--- a/components/bt/host/bluedroid/api/include/api/esp_hidd_api.h
+++ b/components/bt/host/bluedroid/api/include/api/esp_hidd_api.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -16,7 +16,7 @@
 extern "C" {
 #endif
 
-/// subclass of hid device
+/* subclass of hid device */
 #define ESP_HID_CLASS_UNKNOWN      (0x00<<2)           /*!< unknown HID device subclass */
 #define ESP_HID_CLASS_JOS          (0x01<<2)           /*!< joystick */
 #define ESP_HID_CLASS_GPD          (0x02<<2)           /*!< game pad */
@@ -57,9 +57,9 @@ typedef enum {
  */
 typedef enum {
     ESP_HIDD_CONN_STATE_CONNECTED,                   /*!< HID connection established */
-    ESP_HIDD_CONN_STATE_CONNECTING,                  /*!< connection to remote Bluetooth device */
+    ESP_HIDD_CONN_STATE_CONNECTING,                  /*!< connecting to remote Bluetooth device */
     ESP_HIDD_CONN_STATE_DISCONNECTED,                /*!< connection released */
-    ESP_HIDD_CONN_STATE_DISCONNECTING,               /*!< disconnecting to remote Bluetooth device*/
+    ESP_HIDD_CONN_STATE_DISCONNECTING,               /*!< disconnecting from remote Bluetooth device*/
     ESP_HIDD_CONN_STATE_UNKNOWN,                     /*!< unknown connection state */
 } esp_hidd_connection_state_t;
 
@@ -116,32 +116,35 @@ typedef struct {
  * @brief HID device callback function events
  */
 typedef enum {
-    ESP_HIDD_INIT_EVT = 0,       /*!< When HID device is initialized, the event comes */
-    ESP_HIDD_DEINIT_EVT,         /*!< When HID device is deinitialized, the event comes */
-    ESP_HIDD_REGISTER_APP_EVT,   /*!< When HID device application registered, the event comes */
-    ESP_HIDD_UNREGISTER_APP_EVT, /*!< When HID device application unregistered, the event comes */
-    ESP_HIDD_OPEN_EVT,           /*!< When HID device connection to host opened, the event comes */
-    ESP_HIDD_CLOSE_EVT,          /*!< When HID device connection to host closed, the event comes */
-    ESP_HIDD_SEND_REPORT_EVT,    /*!< When HID device send report to lower layer, the event comes */
-    ESP_HIDD_REPORT_ERR_EVT,     /*!< When HID device report handshanke error to lower layer, the event comes */
-    ESP_HIDD_GET_REPORT_EVT,     /*!< When HID device receives GET_REPORT request from host, the event comes */
-    ESP_HIDD_SET_REPORT_EVT,     /*!< When HID device receives SET_REPORT request from host, the event comes */
-    ESP_HIDD_SET_PROTOCOL_EVT,   /*!< When HID device receives SET_PROTOCOL request from host, the event comes */
-    ESP_HIDD_INTR_DATA_EVT,      /*!< When HID device receives DATA from host on intr, the event comes */
-    ESP_HIDD_VC_UNPLUG_EVT,      /*!< When HID device initiates Virtual Cable Unplug, the event comes */
-    ESP_HIDD_API_ERR_EVT         /*!< When HID device has API error, the event comes */
+    ESP_HIDD_INIT_EVT = 0,        /*!< HID device initialized. */
+    ESP_HIDD_DEINIT_EVT,          /*!< HID device deinitialized. */
+    ESP_HIDD_REGISTER_APP_EVT,    /*!< HID device application registered. */
+    ESP_HIDD_UNREGISTER_APP_EVT,  /*!< HID device application unregistered. */
+    ESP_HIDD_OPEN_EVT,            /*!< HID device connection to host opened. */
+    ESP_HIDD_CLOSE_EVT,           /*!< HID device connection to host closed. */
+    ESP_HIDD_SEND_REPORT_EVT,     /*!< HID device sent report to lower layer. */
+    ESP_HIDD_REPORT_ERR_EVT,      /*!< HID device reported handshake error to lower layer. */
+    ESP_HIDD_GET_REPORT_EVT,      /*!< HID device received GET_REPORT request from host. */
+    ESP_HIDD_SET_REPORT_EVT,      /*!< HID device received SET_REPORT request from host. */
+    ESP_HIDD_SET_PROTOCOL_EVT,    /*!< HID device received SET_PROTOCOL request from host. */
+    ESP_HIDD_INTR_DATA_EVT,       /*!< HID device received DATA from host on interrupt channel. */
+    ESP_HIDD_VC_UNPLUG_EVT,       /*!< HID device initiated Virtual Cable Unplug. */
+    ESP_HIDD_API_ERR_EVT          /*!< HID device had API error. */
 } esp_hidd_cb_event_t;
 
+/**
+ * @brief HID device status
+ */
 typedef enum {
-    ESP_HIDD_SUCCESS,
-    ESP_HIDD_ERROR,         /*!< general ESP HD error */
+    ESP_HIDD_SUCCESS,       /*!< successful */
+    ESP_HIDD_ERROR,         /*!< general ESP HID error */
     ESP_HIDD_NO_RES,        /*!< out of system resources */
     ESP_HIDD_BUSY,          /*!< Temporarily can not handle this request. */
     ESP_HIDD_NO_DATA,       /*!< No data. */
-    ESP_HIDD_NEED_INIT,     /*!< HIDD module shall init first */
-    ESP_HIDD_NEED_DEINIT,   /*!< HIDD module shall deinit first */
-    ESP_HIDD_NEED_REG,      /*!< HIDD module shall register first */
-    ESP_HIDD_NEED_DEREG,    /*!< HIDD module shall deregister first */
+    ESP_HIDD_NEED_INIT,     /*!< HIDD module must be initialized first. */
+    ESP_HIDD_NEED_DEINIT,   /*!< HIDD module must be deinitialized first. */
+    ESP_HIDD_NEED_REG,      /*!< HIDD module must be registered first. */
+    ESP_HIDD_NEED_DEREG,    /*!< HIDD module must be deregistered first. */
     ESP_HIDD_NO_CONNECTION, /*!< connection may have been closed */
 } esp_hidd_status_t;
 
@@ -270,8 +273,8 @@ typedef union {
 
 /**
  * @brief           HID device callback function type.
- * @param           event: Event type
- * @param           param: Point to callback parameter, currently is union type
+ * @param[in]       event: Event type
+ * @param[in]       param: Point to callback parameter, currently is union type
  */
 typedef void (*esp_hd_cb_t)(esp_hidd_cb_event_t event, esp_hidd_cb_param_t *param);
 
diff --git a/components/bt/host/bluedroid/api/include/api/esp_hidh_api.h b/components/bt/host/bluedroid/api/include/api/esp_hidh_api.h
index 51a0d43f7b..e23416c211 100644
--- a/components/bt/host/bluedroid/api/include/api/esp_hidh_api.h
+++ b/components/bt/host/bluedroid/api/include/api/esp_hidh_api.h
@@ -52,7 +52,7 @@ typedef enum {
     ESP_HIDH_BUSY,              /*!< vendor-defined: temporarily can not handle this request */
     ESP_HIDH_NO_DATA,           /*!< vendor-defined: no data. */
     ESP_HIDH_NEED_INIT,         /*!< vendor-defined: HIDH module shall initialize first */
-    ESP_HIDH_NEED_DEINIT,       /*!< vendor-defined: HIDH module shall de-deinitialize first */
+    ESP_HIDH_NEED_DEINIT,       /*!< vendor-defined: HIDH module shall deinitialize first */
     ESP_HIDH_NO_CONNECTION,     /*!< vendor-defined: connection may have been closed */
 } esp_hidh_status_t;
 
@@ -309,8 +309,8 @@ typedef union {
 
 /**
  * @brief       HID host callback function type
- * @param       event:      Event type
- * @param       param:      Point to callback parameter, currently is union type
+ * @param[in]   event:      Event type
+ * @param[in]   param:      Point to callback parameter, currently is union type
  */
 typedef void (*esp_hh_cb_t)(esp_hidh_cb_event_t event, esp_hidh_cb_param_t *param);
 
diff --git a/components/bt/host/bluedroid/api/include/api/esp_l2cap_bt_api.h b/components/bt/host/bluedroid/api/include/api/esp_l2cap_bt_api.h
index 982cbdaa85..faa13ccdc5 100644
--- a/components/bt/host/bluedroid/api/include/api/esp_l2cap_bt_api.h
+++ b/components/bt/host/bluedroid/api/include/api/esp_l2cap_bt_api.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -28,17 +28,18 @@ typedef enum {
     ESP_BT_L2CAP_NO_SERVER,              /*!< No server */
 } esp_bt_l2cap_status_t;
 
-/**
- * @brief Security Setting Mask. Use these three mask mode:
- *        1. ESP_BT_L2CAP_SEC_NONE
- *        2. ESP_BT_L2CAP_SEC_AUTHENTICATE
- *        3. (ESP_BT_L2CAP_SEC_ENCRYPT|ESP_BT_L2CAP_SEC_AUTHENTICATE)
+/*
+ * Security setting mask for L2CAP.
+ * - Use one of the following mask modes:
+ *     1. `ESP_BT_L2CAP_SEC_NONE`
+ *     2. `ESP_BT_L2CAP_SEC_AUTHENTICATE`
+ *     3. (`ESP_BT_L2CAP_SEC_ENCRYPT` | `ESP_BT_L2CAP_SEC_AUTHENTICATE`)
  */
 #define ESP_BT_L2CAP_SEC_NONE            0x0000    /*!< No security */
 #define ESP_BT_L2CAP_SEC_AUTHORIZE       0x0001    /*!< Authorization required */
 #define ESP_BT_L2CAP_SEC_AUTHENTICATE    0x0012    /*!< Authentication required */
 #define ESP_BT_L2CAP_SEC_ENCRYPT         0x0024    /*!< Encryption required */
-typedef uint32_t esp_bt_l2cap_cntl_flags_t;
+typedef uint32_t esp_bt_l2cap_cntl_flags_t;        /*!< L2CAP control flags type */
 
 /**
  * @brief L2CAP status parameters
@@ -146,8 +147,8 @@ typedef union {
 /**
  * @brief       L2CAP callback function type.
  *
- * @param       event:      Event type
- * @param       param:      Point to callback parameter, currently is union type
+ * @param[in]   event:      Event type
+ * @param[in]   param:      Point to callback parameter, currently is union type
  */
 typedef void (* esp_bt_l2cap_cb_t)(esp_bt_l2cap_cb_event_t event, esp_bt_l2cap_cb_param_t *param);
 
@@ -203,11 +204,12 @@ esp_err_t esp_bt_l2cap_deinit(void);
 esp_err_t esp_bt_l2cap_connect(esp_bt_l2cap_cntl_flags_t cntl_flag, uint16_t remote_psm, esp_bd_addr_t peer_bd_addr);
 
 /**
- * @brief       This function create a L2CAP server and starts listening for an
- *              L2CAP connection request from a remote Bluetooth device.
- *              When the server is started successfully, the callback is called with ESP_BT_L2CAP_START_EVT.
- *              When the connection is established, the callback is called with ESP_BT_L2CAP_OPEN_EVT.
- *              This function must be called after esp_bt_l2cap_init() successful and before esp_bt_l2cap_deinit().
+* @brief Create an L2CAP server and start listening for connection requests.
+ *
+ * @note
+ *      - When the server is started successfully, the callback is called with `ESP_BT_L2CAP_START_EVT`.
+ *      - When the connection is established, the callback is called with `ESP_BT_L2CAP_OPEN_EVT`.
+ *      - This function must be called after `esp_bt_l2cap_init()` and before `esp_bt_l2cap_deinit()`.
  *
  * @param[in]   cntl_flag:    Lower 16-bit security settings mask.
  * @param[in]   local_psm:    Dynamic PSM.
diff --git a/components/bt/host/bluedroid/api/include/api/esp_sdp_api.h b/components/bt/host/bluedroid/api/include/api/esp_sdp_api.h
index 07b6225a33..e89f63d544 100644
--- a/components/bt/host/bluedroid/api/include/api/esp_sdp_api.h
+++ b/components/bt/host/bluedroid/api/include/api/esp_sdp_api.h
@@ -25,9 +25,13 @@ extern "C" {
 #define ESP_SDP_UUID_SAP      0x112D /*!< SIM Access Profile UUID */
 #define ESP_SDP_UUID_DIP      0x1200 /*!< Device Identification Profile UUID */
 
+/// Build a Bluetooth UUID16
 #define ESP_SDP_BUILD_BT_UUID16(uuid16_val)                                                                                \
     (esp_bt_uuid_t) { .len = ESP_UUID_LEN_16, .uuid = {.uuid16 = (uint16_t)(uuid16_val),}, }
 
+/**
+ * @brief SDP status parameters
+ */
 typedef enum {
     ESP_SDP_SUCCESS = 0,      /*!< Successful operation. */
     ESP_SDP_FAILURE,          /*!< Generic failure. */
@@ -199,8 +203,8 @@ typedef union {
 /**
  * @brief       SDP callback function type.
  *
- * @param       event:      Event type
- * @param       param:      Point to callback parameter, currently is union type
+ * @param[in]   event:      Event type
+ * @param[in]   param:      Point to callback parameter, currently is union type
  */
 typedef void (* esp_sdp_cb_t)(esp_sdp_cb_event_t event, esp_sdp_cb_param_t *param);
 
@@ -241,7 +245,7 @@ esp_err_t esp_sdp_init(void);
 esp_err_t esp_sdp_deinit(void);
 
 /**
- * @brief       This function is called to performs service discovery for the services provided by the given peer device.
+ * @brief       Perform service discovery for the services provided by the given peer device.
  *              When the operation is completed, the callback function will be called with ESP_SDP_SEARCH_COMP_EVT.
  *              This function must be called after esp_sdp_init() successful and before esp_sdp_deinit().
  *
@@ -268,7 +272,7 @@ esp_err_t esp_sdp_search_record(esp_bd_addr_t bd_addr, esp_bt_uuid_t uuid);
 esp_err_t esp_sdp_create_record(esp_bluetooth_sdp_record_t *record);
 
 /**
- * @brief       This function is called to remove a SDP record.
+ * @brief       Remove an SDP record.
  *              When the operation is completed, the callback function will be called with ESP_SDP_REMOVE_RECORD_COMP_EVT.
  *              This function must be called after esp_sdp_init() successful and before esp_sdp_deinit().
  *
diff --git a/components/bt/host/bluedroid/api/include/api/esp_spp_api.h b/components/bt/host/bluedroid/api/include/api/esp_spp_api.h
index e6cdf2fc69..f8a9c52403 100644
--- a/components/bt/host/bluedroid/api/include/api/esp_spp_api.h
+++ b/components/bt/host/bluedroid/api/include/api/esp_spp_api.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -42,15 +42,18 @@ Due to certain limitations, do not use these mask modes:
 2. ESP_SPP_SEC_MODE4_LEVEL4
 3. ESP_SPP_SEC_MITM
 */
-#define ESP_SPP_SEC_NONE            0x0000    /*!< No security. relate to BTA_SEC_NONE in bta/bta_api.h */
-#define ESP_SPP_SEC_AUTHORIZE       0x0001    /*!< Authorization required (only needed for out going connection ) relate to BTA_SEC_AUTHORIZE in bta/bta_api.h*/
-#define ESP_SPP_SEC_AUTHENTICATE    0x0012    /*!< Authentication required.  relate to BTA_SEC_AUTHENTICATE in bta/bta_api.h*/
-#define ESP_SPP_SEC_ENCRYPT         0x0024    /*!< Encryption required.  relate to BTA_SEC_ENCRYPT in bta/bta_api.h*/
-#define ESP_SPP_SEC_MODE4_LEVEL4    0x0040    /*!< Mode 4 level 4 service, i.e. incoming/outgoing MITM and P-256 encryption  relate to BTA_SEC_MODE4_LEVEL4 in bta/bta_api.h*/
-#define ESP_SPP_SEC_MITM            0x3000    /*!< Man-In-The_Middle protection  relate to BTA_SEC_MITM in bta/bta_api.h*/
-#define ESP_SPP_SEC_IN_16_DIGITS    0x4000    /*!< Min 16 digit for pin code  relate to BTA_SEC_IN_16_DIGITS in bta/bta_api.h*/
-typedef uint16_t esp_spp_sec_t;
+#define ESP_SPP_SEC_NONE            0x0000    /*!< No security. */
+#define ESP_SPP_SEC_AUTHORIZE       0x0001    /*!< Authorization required (only needed for out going connection ) */
+#define ESP_SPP_SEC_AUTHENTICATE    0x0012    /*!< Authentication required. */
+#define ESP_SPP_SEC_ENCRYPT         0x0024    /*!< Encryption required. */
+#define ESP_SPP_SEC_MODE4_LEVEL4    0x0040    /*!< Mode 4 level 4 service, i.e. incoming/outgoing MITM and P-256 encryption. */
+#define ESP_SPP_SEC_MITM            0x3000    /*!< Man-In-The-Middle protection. */
+#define ESP_SPP_SEC_IN_16_DIGITS    0x4000    /*!< Min 16 digit for pin code. */
+typedef uint16_t esp_spp_sec_t;               /*!< SPP security type */
 
+/**
+ * @brief SPP status type.
+ */
 typedef enum {
     ESP_SPP_SUCCESS   = 0,          /*!< Successful operation. */
     ESP_SPP_FAILURE,                /*!< Generic failure. */
@@ -63,11 +66,17 @@ typedef enum {
     ESP_SPP_NO_SERVER,              /*!< No SPP server */
 } esp_spp_status_t;
 
+/**
+ * @brief SPP role type.
+ */
 typedef enum {
     ESP_SPP_ROLE_MASTER     = 0,          /*!< Role: master */
     ESP_SPP_ROLE_SLAVE      = 1,          /*!< Role: slave */
 } esp_spp_role_t;
 
+/**
+ * @brief SPP mode type.
+ */
 typedef enum {
     ESP_SPP_MODE_CB         = 0,          /*!< When data is coming, a callback will come with data */
     ESP_SPP_MODE_VFS        = 1,          /*!< Use VFS to write/read data */
@@ -318,7 +327,7 @@ esp_err_t esp_spp_deinit(void);
 
 
 /**
- * @brief       This function is called to performs service discovery for the services provided by the given peer device.
+ * @brief       Perform service discovery for the services provided by the given peer device.
  *              When the operation is completed, the callback function will be called with ESP_SPP_DISCOVERY_COMP_EVT.
  *              This function must be called after esp_spp_init()/esp_spp_enhanced_init() successful and before esp_spp_deinit().
  *
diff --git a/docs/en/api-reference/bluetooth/esp_a2dp.rst b/docs/en/api-reference/bluetooth/esp_a2dp.rst
index 0bf8f6034c..09d6d8f20c 100644
--- a/docs/en/api-reference/bluetooth/esp_a2dp.rst
+++ b/docs/en/api-reference/bluetooth/esp_a2dp.rst
@@ -1,8 +1,13 @@
 Bluetooth® A2DP API
 ===================
 
-Application Example
--------------------
+Overview
+--------
+
+A2DP (Advanced Audio Distribution Profile) enables high-quality audio streaming from one device to another over Bluetooth. It is primarily used for streaming audio from source devices such as smartphones, computers, and media players to sink devices such as Bluetooth speakers, headphones, and car audio systems. Users can use the A2DP APIs to transmit or receive audio streams.
+
+Application Examples
+--------------------
 
 Check :example:`bluetooth/bluedroid/classic_bt` folder in ESP-IDF examples, which contains the following application:
 
diff --git a/docs/en/api-reference/bluetooth/esp_avrc.rst b/docs/en/api-reference/bluetooth/esp_avrc.rst
index de58565acb..4f8bcb18b9 100644
--- a/docs/en/api-reference/bluetooth/esp_avrc.rst
+++ b/docs/en/api-reference/bluetooth/esp_avrc.rst
@@ -1,10 +1,10 @@
-Bluetooth® AVRCP APIs
-=====================
+Bluetooth® AVRCP API
+====================
 
 Overview
 --------
 
-Bluetooth AVRCP reference APIs.
+AVRCP (Audio/Video Remote Control Profile) enables remote control of audio and video devices over Bluetooth, allowing users to manage playback (play, pause, next/previous track), adjust volume, and retrieve media metadata.
 
 Application Examples
 --------------------
diff --git a/docs/en/api-reference/bluetooth/esp_gap_bt.rst b/docs/en/api-reference/bluetooth/esp_gap_bt.rst
index c0a84c1f84..f30ef7edab 100644
--- a/docs/en/api-reference/bluetooth/esp_gap_bt.rst
+++ b/docs/en/api-reference/bluetooth/esp_gap_bt.rst
@@ -1,6 +1,16 @@
-Classic Bluetooth® GAP API
+Bluetooth® Classic GAP API
 ==========================
 
+Overview
+--------
+
+The Bluetooth Classic GAP (Generic Access Profile) API provides interfaces for device discovery, pairing, and security management, allowing applications to control visibility, initiate connections, and configure authentication and encryption for Bluetooth Classic links.
+
+Application Examples
+--------------------
+
+- :example:`bluetooth/bluedroid/classic_bt/bt_discovery` demonstrates how to use APIs to search for a target device with a Major device type of "Phone" or "Audio/Video" in the Class of Device field, and then perform a service discovery via the Service Discovery Protocol.
+
 API Reference
 -------------
 
diff --git a/docs/en/api-reference/bluetooth/esp_hf_ag.rst b/docs/en/api-reference/bluetooth/esp_hf_ag.rst
index a4dcfff36e..1a83588f46 100644
--- a/docs/en/api-reference/bluetooth/esp_hf_ag.rst
+++ b/docs/en/api-reference/bluetooth/esp_hf_ag.rst
@@ -1,5 +1,10 @@
-HFP AG API
-==============
+Bluetooth® HFP AG API
+=====================
+
+Overview
+--------
+
+HFP (Hands-Free Profile) AG API provides functions for a Bluetooth device to act as an Audio Gateway (AG), enabling communication with HFP Client devices such as headsets or car kits. It supports connection management, call handling, volume control, and other hands-free operations.
 
 API Reference
 -------------
diff --git a/docs/en/api-reference/bluetooth/esp_hf_client.rst b/docs/en/api-reference/bluetooth/esp_hf_client.rst
index e08d020035..cb3f520e14 100644
--- a/docs/en/api-reference/bluetooth/esp_hf_client.rst
+++ b/docs/en/api-reference/bluetooth/esp_hf_client.rst
@@ -1,5 +1,10 @@
-HFP Client API
-==============
+Bluetooth® HFP Client API
+=========================
+
+Overview
+--------
+
+HFP (Hands-Free Profile) Client API provides functions to enable a Bluetooth device to act as an HFP Client, allowing communication with an Audio Gateway (AG) device, such as a smartphone, to handle voice calls, volume control, and other hands-free operations.
 
 API Reference
 -------------
diff --git a/docs/en/api-reference/bluetooth/esp_hf_defs.rst b/docs/en/api-reference/bluetooth/esp_hf_defs.rst
index 4f9d3f9d2b..400f11a40d 100644
--- a/docs/en/api-reference/bluetooth/esp_hf_defs.rst
+++ b/docs/en/api-reference/bluetooth/esp_hf_defs.rst
@@ -1,5 +1,17 @@
-HFP Defines
-===========
+Bluetooth® HFP Defines
+======================
+
+Overview
+--------
+
+This file contains definitions for constants, enumerations, and structures used in the Bluetooth Hands-Free Profile (HFP), enabling features like call management, audio control, and network status reporting.
+
+Application Examples
+--------------------
+
+- :example:`bluetooth/bluedroid/classic_bt/hfp_hf` demonstrates how to use the Hands-Free Client Component to communicate with a device that implements Hands-Free Audio Gateway (HF-AG), such as a smartphone.
+
+- :example:`bluetooth/bluedroid/classic_bt/hfp_ag` demonstrates how to use the Hands-Free Audio Gateway (HF-AG) component to communicate with a device that implements Hands-Free Client Role, such as a headphone set. It provides commands for configuring the project, establishing connections, controlling volume, and answering or rejecting calls.
 
 API Reference
 -------------
diff --git a/docs/en/api-reference/bluetooth/esp_l2cap_bt.rst b/docs/en/api-reference/bluetooth/esp_l2cap_bt.rst
index e51fed7205..7065c18a8d 100644
--- a/docs/en/api-reference/bluetooth/esp_l2cap_bt.rst
+++ b/docs/en/api-reference/bluetooth/esp_l2cap_bt.rst
@@ -1,8 +1,13 @@
-Classic Bluetooth® L2CAP API
+Bluetooth® Classic L2CAP API
 ============================
 
-Application Example
--------------------
+Overview
+--------
+
+Bluetooth Classic L2CAP (Logical Link Control and Adaptation Layer Protocol) API provides functions for data transmission between Bluetooth devices. It supports both client and server roles, allowing the creation of L2CAP connections for reliable, high-throughput communication.
+
+Application Examples
+--------------------
 
 Check :example:`bluetooth/bluedroid/classic_bt` folder in ESP-IDF examples, which contains the following application:
 
diff --git a/docs/en/api-reference/bluetooth/esp_sdp.rst b/docs/en/api-reference/bluetooth/esp_sdp.rst
index 75a893731e..3bd53c2423 100644
--- a/docs/en/api-reference/bluetooth/esp_sdp.rst
+++ b/docs/en/api-reference/bluetooth/esp_sdp.rst
@@ -1,10 +1,17 @@
-Bluetooth® SDP APIs
-===================
+Bluetooth® SDP API
+==================
 
 Overview
 --------
 
-Bluetooth SDP reference APIs.
+SDP (Service Discovery Protocol) API enables devices to discover services and service attributes offered by remote Bluetooth devices. It supports service search, service attribute retrieval, and the establishment of service connections.
+
+Application Examples
+--------------------
+
+- :example:`bluetooth/bluedroid/classic_bt/bt_l2cap_client` demonstrates how to use SDP APIs to search for services on remote Bluetooth devices. It shows how to register SDP callbacks, initialize SDP, perform service discovery using ``esp_sdp_search_record()``, and retrieve the L2CAP PSM (Protocol/Service Multiplexer) value from the search results to establish an L2CAP connection.
+
+- :example:`bluetooth/bluedroid/classic_bt/bt_l2cap_server` demonstrates how to use SDP APIs to create and publish service records. It shows how to register SDP callbacks, initialize SDP, create an SDP record using ``esp_sdp_create_record()`` with L2CAP PSM information, making the service discoverable by remote clients.
 
 API Reference
 -------------
diff --git a/docs/en/api-reference/bluetooth/esp_spp.rst b/docs/en/api-reference/bluetooth/esp_spp.rst
index aad387d261..485e9895ab 100644
--- a/docs/en/api-reference/bluetooth/esp_spp.rst
+++ b/docs/en/api-reference/bluetooth/esp_spp.rst
@@ -1,5 +1,10 @@
-SPP API
-=======
+Bluetooth® SPP API
+==================
+
+Overview
+--------
+
+SPP (Serial Port Profile) enables serial communication between Bluetooth devices, allowing them to exchange data over a virtual serial link. SPP API provides functionality to create both SPP initiators (clients) and acceptors (servers), enabling operation under different security requirements.
 
 Application Example
 -------------------