API Comments: Add comments to the API related to PAN and LE Advertiser.

VELAPLATFO-49546

Rootcause:To better assist the use of Bluetooth services for Bluetooth applications, this submission will add commentary descriptions for certain APIs in order to provide instructions for application reference.

Change-Id: I259faeeabe3e5156f161eb06dfdf49eeb44669fe
Signed-off-by: chejinxian1 <[email protected]>

framework/include/bt_le_advertiser.h

@@ -25,6 +25,10 @@ extern "C" {
 #define BTSYMBOLS(s) s
 #endif
 
+/**
+ * @cond
+ */
+
 /**
  * @brief Advertising type
  *
@@ -88,23 +92,57 @@ enum {
 typedef void bt_advertiser_t;
 
 /**
- * @brief Advertising start status callback, invoke on adverting start success or failure
+ * @endcond
+ */
+
+/**
+ * @brief Callback for advertising started notification.
+ *
+ * This callback is used to notify the application of the adverter handle, ID, and
+ * start status of the advertiser. It will be triggered in the following cases:
+ * 1. Advertiser ID allocates failed or the return value of the function "bt_sal_le_start_adv"
+ *    is not "BT_STATUS_SUCCESS" within the advertiser starting event.
+ * 2. 1 second after the successful notification of the start of LE advertising to the
+ *    Bluetooth protocol stack.
  *
- * @param adv - advertiser handle.
- * @param adv_id - advertiser ID.
- * @param status - advertiser start status, BT_ADV_STATUS_SUCCESS on success.
+ * @param adv - Notifies the allocated Advertiser handle.
+ * @param adv_id - Notifies the allocated Advertiser ID.
+ * @param status - Notifies the starting status of the advertiser. BT_ADV_STATUS_SUCCESS
+ *                 indicates that the advertiser has started successfully.
  *
+ * **Example:**
+ * @code
+void on_advertising_start(bt_advertiser_t* adv, uint8_t adv_id, uint8_t status)
+{
+    printf("on_advertising_start, adv_id: %d, status: %d\n", adv_id, status);
+}
+ * @endcode
  */
 typedef void (*on_advertising_start_cb_t)(bt_advertiser_t* adv, uint8_t adv_id, uint8_t status);
 
 /**
- * @brief Advertising stopped notification
+ * @brief Callback for advertising stopped notification.
+ *
+ * This callback is used to notify the application of the handle and ID corresponding to
+ * the stopped advertising.
  *
- * @param adv - advertiser handle
- * @param adv_id - advertiser ID.
+ * @param adv - Advertiser handle.
+ * @param adv_id - Advertiser ID.
+ *
+ * **Example:**
+ * @code
+void on_advertising_stopped(bt_advertiser_t* adv, uint8_t adv_id)
+{
+    printf("on_advertising_stopped, adv_id: %d\n", adv_id);
+}
+ * @endcode
  */
 typedef void (*on_advertising_stopped_cb_t)(bt_advertiser_t* adv, uint8_t adv_id);
 
+/**
+ * @cond
+ */
+
 /**
  * @brief Advertising callback functions structure
  *
@@ -130,16 +168,58 @@ typedef struct {
 } ble_adv_params_t;
 
 /**
- * @brief Start LE advertising
- *
- * @param ins - bluetooth client instance.
- * @param params - advertising parameter.
- * @param adv_data - advertisement data.
- * @param adv_len - length of advertisement data.
- * @param scan_rsp_data - scan response data.
- * @param scan_rsp_len - length of scan response data.
- * @param cbs - advertiser callback functions.
- * @return bt_advertiser_t* - advertiser handle.
+ * @endcond
+ */
+
+/**
+ * @brief Initate LE advertising.
+ *
+ * Before using this function to initiate LE advertising, the Bluetooth application
+ * should set appropriate LE advertising parameters, prepare advertising data and scan
+ * response data, and an advertising callback function. When using this function, the
+ * above content is passed as parameters, and an advertiser handle is returned to indicate
+ * the initiated advertising. With this handle, the Bluetooth application can disable the
+ * corresponding advertising at an appropriate time.
+ *
+ * @param ins - Bluetooth client instance.
+ * @param params - Advertising parameter.
+ * @param adv_data - Advertisement data.
+ * @param adv_len - Length of advertisement data.
+ * @param scan_rsp_data - Scan response data.
+ * @param scan_rsp_len - Length of scan response data.
+ * @param cbs - Advertiser callback functions.
+ * @return bt_advertiser_t* - Advertiser handle.
+ *
+ * **Example:**
+ * @code
+bt_advertiser_t* adver;
+
+void app_start_advertising(bt_instance_t* ins)
+{
+    ble_adv_params_t params;
+    uint8_t adv_data[10];
+    uint8_t scan_rsp_data[10];
+    advertiser_callback_t cbs;
+
+
+    params.adv_type = BT_LE_ADV_IND;
+    params.own_addr_type = BT_LE_ADDR_TYPE_PUBLIC;
+    params.tx_power = -20;
+    params.interval = 100;
+    params.duration = 0;
+    params.channel_map = 7;
+    params.filter_policy = BT_LE_ADV_FILTER_WHITE_LIST_FOR_ALL;
+
+    memset(adv_data, 0, sizeof(adv_data));
+    memset(scan_rsp_data, 0, sizeof(scan_rsp_data));
+
+    cbs.size = sizeof(advertiser_callback_t);
+    cbs.on_advertising_start = on_advertising_start;
+    cbs.on_advertising_stopped = on_advertising_stopped;
+
+    adver = bt_le_start_advertising(ins, &params, adv_data, sizeof(adv_data), scan_rsp_data, sizeof(scan_rsp_data), &cbs);
+}
+ * @endcode
  */
 bt_advertiser_t* BTSYMBOLS(bt_le_start_advertising)(bt_instance_t* ins,
     ble_adv_params_t* params,
@@ -150,27 +230,69 @@ bt_advertiser_t* BTSYMBOLS(bt_le_start_advertising)(bt_instance_t* ins,
     advertiser_callback_t* cbs);
 
 /**
- * @brief Stop LE advertising by advertiser handle
+ * @brief Stop LE advertising by advertiser handle.
  *
- * @param ins - bluetooth client instance.
- * @param adver - advertiser handle.
+ * This function is used to stop the LE advertising indicated by the specified advertiser
+ * handle. Therefore, before using this function, the Bluetooth application should know
+ * the handle corresponding to the initiated advertising. When a Bluetooth application
+ * initiates an advertising, it will be informed of the advertiser handle.
+ *
+ * @param ins - Bluetooth client instance.
+ * @param adver - Advertiser handle.
+ *
+ * **Example:**
+ * @code
+void app_stop_advertising(bt_instance_t* ins)
+{
+    if(!adver)
+        return;
+    bt_le_stop_advertising(ins, adver);
+}
+ * @endcode
  */
 void BTSYMBOLS(bt_le_stop_advertising)(bt_instance_t* ins, bt_advertiser_t* adver);
 
 /**
- * @brief Stop LE advertising by adver id
+ * @brief Stop LE advertising by advertiser ID.
+ *
+ * This function is used to stop the LE advertising indicated by the specified advertiser ID.
+ * Therefore, before using this function, the Bluetooth application should know the ID
+ * corresponding to the initiated advertising. When a Bluetooth application successfully initiates
+ * an advertising, the advertiser ID will be informed through the "on_advertising_start_cb_t"
+ * callback function provided when the advertising is initiated by the application.
+ *
+ * @param ins - Bluetooth client instance.
+ * @param adv_id - Advertiser ID.
  *
- * @param ins - bluetooth client instance.
- * @param adv_id - advertiser ID.
+ * **Example:**
+ * @code
+void app_stop_advertising(bt_instance_t* ins, uint8_t adv_id)
+{
+    bt_le_stop_advertising_id(ins, adv_id);
+}
+ * @endcode
  */
 void BTSYMBOLS(bt_le_stop_advertising_id)(bt_instance_t* ins, uint8_t adv_id);
 
 /**
- * @brief Check is advertising supported
+ * @brief Check if LE advertising is supported.
+ *
+ * This function is used to check if the Bluetooth protocol stack supports LE advertising for
+ * Bluetooth applications.
  *
- * @param ins - bluetooth client instance.
- * @return true - support.
- * @return false - not support.
+ * @param ins - Bluetooth client instance.
+ * @return bool - true represents support for LE advertising, while false represents non-support.
+ *
+ * **Example:**
+ * @code
+void app_check_advertising_support(bt_instance_t* ins)
+{
+    if(bt_le_advertising_is_supported(ins))
+        printf("advertising is supported\n");
+    else
+        printf("advertising is not supported\n");
+}
+ * @endcode
  */
 bool BTSYMBOLS(bt_le_advertising_is_supported)(bt_instance_t* ins);