BLE: Document ble::ScanParameters.

features/FEATURE_BLE/ble/gap/ScanParameters.h

@@ -30,6 +30,24 @@
 
 namespace ble {
 
+/**
+ * Parameters defining the scan process.
+ *
+ * The scan process is defined by two main parameters:
+ *   - The scan window that defines how long the device should scan.
+ *   - The scan window that defines how frequently the device should scan.
+ *
+ * To scan continuously, the scan window and the scan interval should have the
+ * same value.
+ *
+ * To get extra data from the advertising device, the scanner can send scan
+ * requests to the advertiser that respond with a scan response. It is possible
+ * to select what type of address is used to issue the scan request.
+ *
+ * With Bluetooth 5, devices can advertise on more physical channels and by
+ * extension they can scan on more physical channel. It is possible to define
+ * independent scan parameters for every scannable physical channel.
+ */
 class ScanParameters {
 public:
 
@@ -120,28 +138,50 @@ public:
         }
     }
 
+    /**
+     * Set the address type used for scan requests.
+     * @param address The type of address to use during scan requests.
+     * @return A reference to this object.
+     */
     ScanParameters &setOwnAddressType(own_address_type_t address)
     {
         own_address_type = address;
         return *this;
     }
 
+    /**
+     * Get the address type used during scan requests.
+     */
     own_address_type_t getOwnAddressType() const
     {
         return own_address_type;
     }
 
+    /**
+     * Set the filter to apply during scanning.
+     * @param filter_policy The filter to apply during scannong.
+     * @return A reference to this object.
+     */
     ScanParameters &setFilter(scanning_filter_policy_t filter_policy)
     {
         scanning_filter_policy = filter_policy;
         return *this;
     }
 
+    /**
+     * Get the filter to use during scanning
+     */
     scanning_filter_policy_t getFilter() const
     {
         return scanning_filter_policy;
     }
 
+    /**
+     * Enable or disable phys that should be used during scanning .
+     * @param enable_1m True to enable the 1M phy and false to disable it.
+     * @param enable_coded True to enable the coded phy and false to disable it.
+     * @return A reference to this object.
+     */
     ScanParameters &setPhys(bool enable_1m, bool enable_coded)
     {
         phys.set_1m(enable_1m);
@@ -149,11 +189,21 @@ public:
         return *this;
     }
 
+    /**
+     * Get the phys to use during scanning.
+     */
     phy_set_t getPhys() const
     {
         return phys;
     }
 
+    /**
+     * Set the 1M scan configuration.
+     * @param interval The scan interval to use.
+     * @param window The scan window to use.
+     * @param active_scanning The active scanning flag.
+     * @return A reference to this object.
+     */
     ScanParameters &set1mPhyConfiguration(
         scan_interval_t interval,
         scan_window_t window,
@@ -167,11 +217,21 @@ public:
         return *this;
     }
 
+    /**
+     * Get the 1M scan configuration.
+     */
     phy_configuration_t get1mPhyConfiguration() const
     {
         return phy_1m_configuration;
     }
 
+    /**
+     * Set the coded phy scan configuration.
+     * @param interval The scan interval to use.
+     * @param window The scan window to use.
+     * @param active_scanning The active scanning flag.
+     * @return A reference to this object.
+     */
     ScanParameters &setCodedPhyConfiguration(
         scan_interval_t interval,
         scan_window_t window,
@@ -185,6 +245,9 @@ public:
         return *this;
     }
 
+    /**
+     * Get the coded phy scan configuration.
+     */
     phy_configuration_t getCodedPhyConfiguration() const
     {
         return phy_1m_configuration;