From d2d3ce7f0c31cd472733aab14852d512f884baef Mon Sep 17 00:00:00 2001
From: zhanghaipeng <zhanghaipeng@espressif.com>
Date: Wed, 10 Jul 2024 14:58:34 +0800
Subject: [PATCH] docs(ble/bluedroid): Optimize doc for registering BLE
 callback functions

---
 .../bt/host/bluedroid/api/include/api/esp_gap_ble_api.h     | 2 ++
 .../bt/host/bluedroid/api/include/api/esp_gattc_api.h       | 2 ++
 .../bt/host/bluedroid/api/include/api/esp_gatts_api.h       | 2 ++
 .../bluetooth/bluedroid/ble/gatt_client/main/gattc_demo.c   | 6 +++---
 .../bluetooth/bluedroid/ble/gatt_server/main/gatts_demo.c   | 2 +-
 5 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h b/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h
index 5fd20de0a8..e1a0f325d5 100644
--- a/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h
+++ b/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h
@@ -1593,6 +1593,8 @@ typedef void (* esp_gap_ble_cb_t)(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_p
  *
  * @param[in]       callback: callback function
  *
+ * @note            Avoid performing time-consuming operations within the callback functions.
+ *
  * @return
  *                  - ESP_OK : success
  *                  - other  : failed
diff --git a/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h b/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h
index 0f5b83d351..0d9837a5ca 100644
--- a/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h
+++ b/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h
@@ -272,6 +272,8 @@ typedef void (* esp_gattc_cb_t)(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_
  *
  * @param[in]      callback The pointer to the application callback function
  *
+ * @note            Avoid performing time-consuming operations within the callback functions.
+ *
  * @return
  *          - ESP_OK: Success
  *          - ESP_FAIL: Failure
diff --git a/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h b/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h
index 420cc80359..642222104a 100644
--- a/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h
+++ b/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h
@@ -283,6 +283,8 @@ typedef void (* esp_gatts_cb_t)(esp_gatts_cb_event_t event, esp_gatt_if_t gatts_
  *
  * @param[in] callback The pointer to the application callback function
  *
+ * @note            Avoid performing time-consuming operations within the callback functions.
+ *
  * @return
  *       - ESP_OK: Success
  *       - ESP_FAIL: Failure
diff --git a/examples/bluetooth/bluedroid/ble/gatt_client/main/gattc_demo.c b/examples/bluetooth/bluedroid/ble/gatt_client/main/gattc_demo.c
index bde14e5ea8..43873a8bbf 100644
--- a/examples/bluetooth/bluedroid/ble/gatt_client/main/gattc_demo.c
+++ b/examples/bluetooth/bluedroid/ble/gatt_client/main/gattc_demo.c
@@ -483,15 +483,15 @@ void app_main(void)
         ESP_LOGE(GATTC_TAG, "%s enable bluetooth failed: %s\n", __func__, esp_err_to_name(ret));
         return;
     }
-
-    //register the  callback function to the gap module
+    // Note: Avoid performing time-consuming operations within callback functions.
+    // Register the callback function to the gap module
     ret = esp_ble_gap_register_callback(esp_gap_cb);
     if (ret){
         ESP_LOGE(GATTC_TAG, "%s gap register failed, error code = %x\n", __func__, ret);
         return;
     }
 
-    //register the callback function to the gattc module
+    // Register the callback function to the gattc module
     ret = esp_ble_gattc_register_callback(esp_gattc_cb);
     if(ret){
         ESP_LOGE(GATTC_TAG, "%s gattc register failed, error code = %x\n", __func__, ret);
diff --git a/examples/bluetooth/bluedroid/ble/gatt_server/main/gatts_demo.c b/examples/bluetooth/bluedroid/ble/gatt_server/main/gatts_demo.c
index 244938b151..b31b86ec02 100644
--- a/examples/bluetooth/bluedroid/ble/gatt_server/main/gatts_demo.c
+++ b/examples/bluetooth/bluedroid/ble/gatt_server/main/gatts_demo.c
@@ -718,7 +718,7 @@ void app_main(void)
         ESP_LOGE(GATTS_TAG, "%s enable bluetooth failed: %s\n", __func__, esp_err_to_name(ret));
         return;
     }
-
+    // Note: Avoid performing time-consuming operations within callback functions.
     ret = esp_ble_gatts_register_callback(gatts_event_handler);
     if (ret){
         ESP_LOGE(GATTS_TAG, "gatts register error, error code = %x", ret);