docs

features/FEATURE_BLE/ble/generic/GenericGap.h

@@ -51,9 +51,9 @@ public:
     static const uint8_t MAX_ADVERTISING_SETS = 15;
     static const size_t MAX_HCI_DATA_LENGTH = 251;
     /**
-     * Construct a GenericGap instance for a given BLE instance ID.
+     * Construct a GenericGap.
      *
-     * @param ble_instance_id Id of the BLE instance using this instance.
+     * @param event_queue Event queue used to serialise execution.
      *
      * @param pal_gap GAP Platform abstraction instance containing the base GAP
      * primitives.
@@ -76,44 +76,66 @@ public:
      */
     virtual ~GenericGap();
 
+    /** @copydoc Gap::getMaxAdvertisingSetNumber
+     */
     uint8_t getMaxAdvertisingSetNumber();
 
+    /** @copydoc Gap::getMaxAdvertisingDataLength
+     */
     uint8_t getMaxAdvertisingDataLength();
 
+    /** @copydoc Gap::createAdvertisingSet
+     */
     ble_error_t createAdvertisingSet(
         AdvHandle_t *handle,
         const AdvertisingParameters &parameters
     );
 
+    /** @copydoc Gap::destroyAdvertisingSet
+     */
     ble_error_t destroyAdvertisingSet(AdvHandle_t handle);
 
+    /** @copydoc Gap::setAdvertisingParams
+     */
     ble_error_t setAdvertisingParams(
         AdvHandle_t handle,
         const AdvertisingParameters &params
     );
 
+    /** @copydoc Gap::setAdvertisingPayload
+     */
     ble_error_t setAdvertisingPayload(
         AdvHandle_t handle,
         mbed::Span<uint8_t> payload,
         bool minimiseFragmentation
     );
 
+    /** @copydoc Gap::setAdvertisingScanResponse
+     */
     ble_error_t setAdvertisingScanResponse(
         AdvHandle_t handle,
         mbed::Span<uint8_t> response,
         bool minimiseFragmentation
     );
 
+    /** @copydoc Gap::startAdvertising
+     */
     ble_error_t startAdvertising(
         AdvHandle_t handle,
         adv_duration_t maxDuration,
         uint8_t maxEvents
     );
 
+    /** @copydoc Gap::stopAdvertising
+     */
     ble_error_t stopAdvertising(AdvHandle_t handle);
 
+    /** @copydoc Gap::isAdvertisingActive
+     */
     bool isAdvertisingActive(AdvHandle_t handle);
 
+    /** @copydoc Gap::setPeriodicAdvertisingParameters
+     */
     virtual ble_error_t setPeriodicAdvertisingParameters(
         AdvHandle_t handle,
         periodic_interval_t periodicAdvertisingIntervalMin,
@@ -121,25 +143,39 @@ public:
         bool advertiseTxPower
     );
 
+    /** @copydoc Gap::setPeriodicAdvertisingPayload
+     */
     virtual ble_error_t setPeriodicAdvertisingPayload(
         AdvHandle_t handle,
         mbed::Span<uint8_t> payload
     );
 
+    /** @copydoc Gap::startPeriodicAdvertising
+     */
     virtual ble_error_t startPeriodicAdvertising(AdvHandle_t handle);
 
+    /** @copydoc Gap::stopPeriodicAdvertising
+     */
     virtual ble_error_t stopPeriodicAdvertising(AdvHandle_t handle);
 
+    /** @copydoc Gap::isPeriodicAdvertisingActive
+     */
     virtual bool isPeriodicAdvertisingActive(AdvHandle_t handle);
 
+    /** @copydoc Gap::setScanParameters
+     */
     virtual ble_error_t setScanParameters(const ScanParameters &params);
 
+    /** @copydoc Gap::startScan
+     */
     virtual ble_error_t startScan(
         scanning_filter_duplicates_t filtering,
         scan_duration_t duration,
         scan_period_t period
     );
 
+    /** @copydoc Gap::createSync
+     */
     virtual ble_error_t createSync(
         PeerAddressType_t peerAddressType,
         uint8_t *peerAddress,
@@ -148,29 +184,43 @@ public:
         sync_timeout_t timeout
     );
 
+    /** @copydoc Gap::createSync
+     */
     virtual ble_error_t createSync(
         slave_latency_t maxPacketSkip,
         sync_timeout_t timeout
     );
 
+    /** @copydoc Gap::cancelCreateSync
+     */
     virtual ble_error_t cancelCreateSync();
 
+    /** @copydoc Gap::terminateSync
+     */
     virtual ble_error_t terminateSync(PeriodicSyncHandle_t handle);
 
+    /** @copydoc Gap::addDeviceToPeriodicAdvertiserList
+     */
     virtual ble_error_t addDeviceToPeriodicAdvertiserList(
         PeerAddressType_t peerAddressType,
         Address_t peerAddress,
         uint8_t sid
     );
 
+    /** @copydoc Gap::removeDeviceFromPeriodicAdvertiserList
+     */
     virtual ble_error_t removeDeviceFromPeriodicAdvertiserList(
         PeerAddressType_t peerAddressType,
         uint8_t *peerAddress,
         uint8_t sid
     );
 
+    /** @copydoc Gap::clearPeriodicAdvertiserList
+     */
     virtual ble_error_t clearPeriodicAdvertiserList();
 
+    /** @copydoc Gap::getMaxPeriodicAdvertiserListSize
+     */
     virtual uint8_t getMaxPeriodicAdvertiserListSize();
 
     /**

features/FEATURE_BLE/ble/pal/PalGap.h

@@ -134,23 +134,21 @@ struct Gap {
             clock_accuracy_t master_clock_accuracy
         ) = 0;
 
-        /**
-         * Should be invoked by the Gap implementation when an extended
-         * advertising report event happens.
+        /** Called on advertising report event.
          *
-         * @param event_type
-         * @param address_type
-         * @param address
-         * @param primary_phy
-         * @param secondary_phy
-         * @param advertising_sid
-         * @param tx_power
-         * @param rssi
-         * @param periodic_advertising_interval
-         * @param direct_address_type
-         * @param direct_address
-         * @param data_length
-         * @param data_size
+         * @param event_type Type of advertising used.
+         * @param address_type Peer address type of advertiser.
+         * @param address Peer address of advertiser.
+         * @param primary_phy PHY used on the primary channels.
+         * @param secondary_phy PHY used on secondary channels.
+         * @param advertising_sid Set identification number.
+         * @param tx_power Transmission power reported by the packet.
+         * @param rssi Measured signal strength.
+         * @param periodic_advertising_interval Interval of periodic advertising.
+         * @param direct_address_type Directed advertising target address type.
+         * @param direct_address Directed advertising target address.
+         * @param data_length Advertising payload length.
+         * @param data Advertising payload.
          *
          * @note: See Bluetooth 5 Vol 2 PartE: 7.7.65.13 LE extended advertising
          * report event.
@@ -171,18 +169,16 @@ struct Gap {
             const uint8_t *data_size
         ) = 0;
 
-        /**
-         * TODO
-         * @param error
-         * @param sync_handle
-         * @param advertising_sid
-         * @param advertiser_address_type
-         * @param advertiser_address
-         * @param periodic_advertising_interval
-         * @param clock_accuracy
+        /** Called on advertising sync event.
          *
-         * @note: See Bluetooth 5 Vol 2 PartE: 7.7.65.14 LE extended advertising
-         * report event.
+         * @param error SUCCESS if synchronisation was achieved.
+         * @param sync_handle Advertising sync handle.
+         * @param advertising_sid Advertising set identifier.
+         * @param advertiser_address_type Peer address type.
+         * @param advertiser_address Peer address.
+         * @param advertiser_phy PHY used for advertisements.
+         * @param periodic_advertising_interval Periodic advertising interval.
+         * @param clock_accuracy Peer clock accuracy.
          */
         virtual void on_periodic_advertising_sync_established(
             pal::hci_error_code_t error,
@@ -195,14 +191,14 @@ struct Gap {
             pal::clock_accuracy_t clock_accuracy
         ) = 0;
 
-        /**
-         * TODO
-         * @param sync_handle
-         * @param tx_power
-         * @param rssi
-         * @param data_status
-         * @param data_length
-         * @param data
+        /** Called after a periodic advertising report event.
+         *
+         * @param sync_handle Periodic advertising sync handle
+         * @param tx_power TX power.
+         * @param rssi Received signal strength.
+         * @param data_status Status to indicate the completeness of the payload.
+         * @param data_length Periodic advertisement payload length.
+         * @param data Periodic advertisement payload.
          */
         virtual void on_periodic_advertising_report(
             sync_handle_t sync_handle,
@@ -213,25 +209,24 @@ struct Gap {
             const uint8_t *data
         ) = 0;
 
-        /**
-         * TODO
-         * @param sync_handle
+        /** Called on periodic advertising sync loss event.
+         *
+         * @param sync_handle Advertising sync handle'
          */
         virtual void on_periodic_advertising_sync_loss(
             sync_handle_t sync_handle
         ) = 0;
 
-        /**
-         * TODO
+        /** Called when scanning times out.
          */
         virtual void on_scan_timeout() = 0;
 
-        /**
-         * TODO
-         * @param status
-         * @param advertising_handle
-         * @param connection_handle
-         * @param number_of_completed_extended_advertising_events
+        /** Called when advertising set stops advertising.
+         *
+         * @param status SUCCESS if connection has been established.
+         * @param advertising_handle Advertising set handle.
+         * @param advertising_handle Connection handle.
+         * @param number_of_completed_extended_advertising_events Number of events created during before advertising end.
          */
         virtual void on_advertising_set_terminated(
             hci_error_code_t status,
@@ -240,11 +235,11 @@ struct Gap {
             uint8_t number_of_completed_extended_advertising_events
         ) = 0;
 
-        /**
-         * TODO
-         * @param advertising_handle
-         * @param scanner_address_type
-         * @param address
+        /** Called when a device receives a scan request from an active scanning device.
+         *
+         * @param advertising_handle Advertising set handle.
+         * @param scanner_address_type Peer address type.
+         * @param address Peer address.
          */
         virtual void on_scan_request_received(
             advertising_handle_t advertising_handle,