From f9b60f6f74f421a7d1ca61d79d3658d9eae367a1 Mon Sep 17 00:00:00 2001
From: Zhang Hai Peng <zhanghaipeng@espressif.com>
Date: Mon, 6 Jan 2025 11:13:43 +0800
Subject: [PATCH] docs(ble/bluedroid): Optimize doc for registering BLE
 callback functions

(cherry picked from commit d84ccadf905bcaadcfbdee0b61e8875775ff716f)

Co-authored-by: zhanghaipeng <zhanghaipeng@espressif.com>
---
 .../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 902a00295f..367ecf733d 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 d422224e44..e5cc1ef3f7 100644
--- a/examples/bluetooth/bluedroid/ble/gatt_client/main/gattc_demo.c
+++ b/examples/bluetooth/bluedroid/ble/gatt_client/main/gattc_demo.c
@@ -493,15 +493,15 @@ void app_main(void)
         ESP_LOGE(GATTC_TAG, "%s enable bluetooth failed: %s", __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", __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", __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 8b0f4c3c13..3502b785f4 100644
--- a/examples/bluetooth/bluedroid/ble/gatt_server/main/gatts_demo.c
+++ b/examples/bluetooth/bluedroid/ble/gatt_server/main/gatts_demo.c
@@ -724,7 +724,7 @@ void app_main(void)
         ESP_LOGE(GATTS_TAG, "%s enable bluetooth failed: %s", __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);