SAL: add descriptions for PA sync APIs.

bug: v/82275

This patch includes the documentation of SAL APIs.

Change-Id: Iaa82371c55368eca938257b410aa3e55dba5d6cc
Signed-off-by: Zihao Gao <[email protected]>

Author: gzh-terry

service/stacks/include/sal_pa_sync_interface.h

@@ -91,10 +91,69 @@ typedef struct bt_sal_pa_sync_param {
     uint8_t cte: /**< Sync_CTE_Type, e.g., BT_SAL_PA_SYNC_CTE_TYPE_NO_AOA */
 } bt_sal_pa_sync_param_t;
 
+/**
+ * @brief LE Periodic Advertising Create Sync command.
+ *
+ * This command is used to synchronize with a single periodic advertising train from an advertiser
+ * and begin receiving periodic advertising packets.
+ *
+ * @param[in] id The Controller ID.
+ * @param[in] params The parameters used to synchronize the periodic advertising train.
+ *
+ * A @ref SYNC_ESTABLISHED event, associated with a @p handle, shall be generated when starting to
+ * receive periodic advertising packets.
+ * A @ref SYNC_TERMINATED event shall be generated if the sync fails to establish.
+ * A @ref SYNC_REPORT event may be generated when a periodic advertising packet is received.
+ */
 bt_status_t bt_sal_pa_create_sync(bt_controller_id_t id, const bt_sal_pa_sync_param_t* params);
+
+/**
+ * @brief LE Periodic Advertising Terminate Sync command.
+ *
+ * This command is used to stop reception of the periodic advertising train identified by the
+ * @p handle.
+ *
+ * @param[in] id The Controller ID.
+ * @param[in] handle The Sync_Handle obtained from the @ref SYNC_ESTABLISHED event.
+ *
+ * A @ref SYNC_TERMINATED event shall be generated when this command is completed.
+ */
 bt_status_t bt_sal_pa_terminate_sync(bt_controller_id_t id, uint16_t handle);
+
+/**
+ * @brief LE Add Device To Periodic Advertiser List command.
+ *
+ * This command is used to add an entry, consisting of a single device address and SID, to the
+ * Periodic Advertiser list stored in the Controller.
+ *
+ * @param[in] id The Controller ID.
+ * @param[in] sid The Advertising SID.
+ * @param[in] addr Public device address, random device address, public identity address, or random
+ *                 (static) identity address of the advertiser.
+ */
 bt_status_t bt_sal_pa_list_add(bt_controller_id_t id, uint8_t sid, bt_le_address_t addr);
+
+/**
+ * @brief LE Remove Device From Periodic Advertiser List command.
+ *
+ * This command is used to remove one entry from the list of Periodic Advertisers stored in the
+ * Controller.
+ *
+ * @param[in] id The Controller ID.
+ * @param[in] sid The Advertising SID.
+ * @param[in] addr Public device address, random device address, public identity address, or random
+ *                 (static) identity address of the advertiser.
+ */
 bt_status_t bt_sal_pa_list_remove(bt_controller_id_t id, uint8_t sid, bt_le_address_t addr);
+
+/**
+ * @brief LE Clear Periodic Advertiser List command.
+ *
+ * This command is used to remove all entries from the list of periodic advertisers in the
+ * Controller.
+ *
+ * @param[in] id The Controller ID.
+ */
 bt_status_t bt_sal_pa_list_clear(bt_controller_id_t id);
 
 #endif /* __SAL_PA_SYNC_INTERFACE_H__ */