Bluetooth: framework/include/bt_le_scan.h, comments.

bug: V/45986

Signed-off-by: zhongzhijie1 <[email protected]>

framework/include/bt_le_scan.h

@@ -30,6 +30,10 @@ extern "C" {
 
 #define BLE_SCAN_FILTER_UUID_MAX_NUM 2
 
+/**
+ * @cond
+ */
+
 /**
  * @brief Scan start status code
  *
@@ -121,30 +125,76 @@ typedef struct {
     uint8_t active;
     uint8_t duplicated;
 } ble_scan_filter_t;
+/**
+ * @endcond
+ */
 
 /**
- * @brief scan result callback
+ * @brief Scan result callback function.
  *
- * @param scanner - scanner handle.
- * @param result - scan result.
+ * Callback function called when a scan result is available.
+ *
+ * @param scanner - Scanner handle.
+ * @param result - Pointer to the scan result, see @ref ble_scan_result_t.
+ *
+ * **Example:**
+ * @code
+void le_scan_result_callback(bt_scanner_t* scanner, ble_scan_result_t* result)
+{
+    // Process scan result
+}
+
+static scanner_callbacks_t lescan_cbs = {
+    .size = sizeof(lescan_cbs),
+    .on_scan_result = le_scan_result_callback,
+};
+ * @endcode
  */
 typedef void (*on_scan_result_cb_t)(bt_scanner_t* scanner, ble_scan_result_t* result);
 
 /**
- * @brief Scan start status callback
+ * @brief Scan start status callback function.
  *
- * @param scanner - scanner handle.
- * @param result - scan start status, BT_SCAN_STATUS_SUCCESS on success.
+ * Callback function called when the scan starts or fails to start.
+ *
+ * @param scanner - Scanner handle.
+ * @param status - Scan start status code, see scan status codes.
+ *
+ * **Example:**
+ * @code
+void on_scan_status(bt_scanner_t* scanner, uint8_t status)
+{
+    if (status == BT_SCAN_STATUS_SUCCESS) {
+        // Scan started successfully
+    } else {
+        // Handle scan start failure
+    }
+}
+ * @endcode
  */
 typedef void (*on_scan_status_cb_t)(bt_scanner_t* scanner, uint8_t status);
 
 /**
- * @brief Scan stopped callback
+ * @brief Scan stopped callback function.
+ *
+ * Callback function called when the scan is stopped.
+ *
+ * @param scanner - Scanner handle.
  *
- * @param scanner - scanner handle.
+ * **Example:**
+ * @code
+void on_scan_stopped(bt_scanner_t* scanner)
+{
+    // Handle scan stopped event
+}
+ * @endcode
  */
 typedef void (*on_scan_stopped_cb_t)(bt_scanner_t* scanner);
 
+/**
+ * @cond
+ */
+
 /**
  * @brief Scanner callback structure
  *
@@ -155,62 +205,122 @@ typedef struct {
     on_scan_status_cb_t on_scan_start_status;
     on_scan_stopped_cb_t on_scan_stopped;
 } scanner_callbacks_t;
+/**
+ * @endcond
+ */
 
 /**
- * @brief Start LE scan
+ * @brief Start BLE scan.
+ *
+ * Initiates a BLE scan with default settings.
  *
- * @param ins - bluetooth client instance.
- * @param cbs - scan callback function.
- * @return bt_scanner_t* - scanner handle generated by scan manager.
+ * @param ins - Bluetooth client instance, see @ref bt_instance_t.
+ * @param cbs - Pointer to scanner callbacks, see @ref scanner_callbacks_t.
+ * @return bt_scanner_t* - Scanner handle generated by the scan manager.
+ *
+ * **Example:**
+ * @code
+bt_scanner_t* scanner = bt_le_start_scan(ins, &my_scanner_callbacks);
+if (scanner == NULL) {
+    // Handle error
+}
+ * @endcode
  */
 bt_scanner_t* BTSYMBOLS(bt_le_start_scan)(bt_instance_t* ins, const scanner_callbacks_t* cbs);
 
 /**
- * @brief Start LE scan with scan settings
+ * @brief Start BLE scan with specific settings.
  *
- * @param ins - bluetooth client instance.
- * @param settings - scan settings with scan mode and scan phy.
- * @param cbs - scan callback function.
- * @return bt_scanner_t* - scanner handle generated by scan manager.
+ * Initiates a BLE scan with provided scan settings.
+ *
+ * @param ins - Bluetooth client instance, see @ref bt_instance_t.
+ * @param settings - Pointer to scan settings, see @ref ble_scan_settings_t.
+ * @param cbs - Pointer to scanner callbacks, see @ref scanner_callbacks_t.
+ * @return bt_scanner_t* - Scanner handle generated by the scan manager.
+ *
+ * **Example:**
+ * @code
+ble_scan_settings_t settings = {
+    .scan_mode = BT_SCAN_MODE_LOW_LATENCY,
+    .scan_type = BT_LE_SCAN_TYPE_ACTIVE,
+    // Additional settings...
+};
+bt_scanner_t* scanner = bt_le_start_scan_settings(ins, &settings, &my_scanner_callbacks);
+if (scanner == NULL) {
+    // Handle error
+}
+ * @endcode
  */
 bt_scanner_t* BTSYMBOLS(bt_le_start_scan_settings)(bt_instance_t* ins,
     ble_scan_settings_t* settings,
     const scanner_callbacks_t* cbs);
 
 /**
- * @brief Start LE scan with scan filters
+ * @brief Start BLE scan with filters.
  *
- * @param ins - bluetooth client instance.
- * @param settings - scan settings with scan mode and scan phy.
- * @param filter_data - filter data.
- * @param filter_length - filter data length.
- * @param cbs - scan callback function.
- * @return bt_scanner_t* - scanner handle generated by scan manager.
+ * Initiates a BLE scan with specific settings and filters.
+ *
+ * @param ins - Bluetooth client instance, see @ref bt_instance_t.
+ * @param settings - Pointer to scan settings, see @ref ble_scan_settings_t.
+ * @param filter_data - Pointer to filter data, see @ref ble_scan_filter_t.
+ * @param cbs - Pointer to scanner callbacks, see @ref scanner_callbacks_t.
+ * @return bt_scanner_t* - Scanner handle generated by the scan manager.
+ *
+ * **Example:**
+ * @code
+ble_scan_filter_t filter = {
+    .uuids = {0x180D, 0x180F}, // Heart Rate and Battery Service UUIDs
+    .active = 1,
+    // Additional filter settings...
+};
+bt_scanner_t* scanner = bt_le_start_scan_with_filters(ins, &settings, &filter, &my_scanner_callbacks);
+if (scanner == NULL) {
+    // Handle error
+}
+ * @endcode
  */
 bt_scanner_t* BTSYMBOLS(bt_le_start_scan_with_filters)(bt_instance_t* ins,
     ble_scan_settings_t* settings,
     ble_scan_filter_t* filter_data,
     const scanner_callbacks_t* cbs);
 
 /**
- * @brief Stop LE scan
+ * @brief Stop BLE scan.
+ *
+ * Stops an ongoing BLE scan.
  *
- * @param ins - bluetooth client instance.
- * @param scanner - scanner handle generated by scan manager.
+ * @param ins - Bluetooth client instance, see @ref bt_instance_t.
+ * @param scanner - Scanner handle generated by the scan manager.
+ *
+ * **Example:**
+ * @code
+bt_le_stop_scan(ins, scanner);
+ * @endcode
  */
 void BTSYMBOLS(bt_le_stop_scan)(bt_instance_t* ins, bt_scanner_t* scanner);
 
 /**
- * @brief Check LE scan is support
+ * @brief Check if BLE scanning is supported.
+ *
+ * Determines whether BLE scanning is supported by the adapter.
  *
- * @param ins - bluetooth client instance.
- * @return true - support.
- * @return false - not support.
+ * @param ins - Bluetooth client instance, see @ref bt_instance_t.
+ * @return true - Scanning is supported.
+ * @return false - Scanning is not supported.
+ *
+ * **Example:**
+ * @code
+if (bt_le_scan_is_supported(ins)) {
+    // Scanning is supported
+} else {
+    // Scanning is not supported
+}
+ * @endcode
  */
 bool BTSYMBOLS(bt_le_scan_is_supported)(bt_instance_t* ins);
 
 #ifdef __cplusplus
 }
 #endif
 
-#endif /* __BT_LE_SCAN_H_ */
+#endif /* __BT_LE_SCAN_H_ */