BLE: Update documentation.

Fix typos, spelling and conjugation.

Author: pan-

features/FEATURE_BLE/ble/BLE.h

@@ -202,7 +202,7 @@ class BLE
         OnEventsToProcessCallback_t;
 
     /**
-     * Register a callback called when the BLE stack has pending  work.
+     * Register a callback called when the BLE stack has pending work.
      *
      * By registering a callback, application code can know when event processing
      * has to be scheduled.

features/FEATURE_BLE/ble/BLEInstanceBase.h

@@ -89,8 +89,8 @@ class BLEInstanceBase
     /**
      * Start the initialization of the vendor BLE subsystem.
      *
-     * Call to this function is initiated by BLE::init, instanceID identify the
-     * BLE instance which issue that call while the initCallback is used to
+     * Calls to this function are initiated by BLE::init, instanceID identify
+     * the BLE instance which issue that call while the initCallback is used to
      * signal asynchronously the completion of the initialization process.
      *
      * @param[in] instanceID Identifier of the BLE instance requesting
@@ -166,7 +166,8 @@ class BLEInstanceBase
     /**
      * Accessor to the vendor implementation of the Gap interface.
      *
-     * @return A reference to a Gap object associated to this BLE instance.
+     * @return A reference to a Gap object associated to this BLEInstanceBase
+     * instance.
      *
      * @see BLE::gap() Gap
      */
@@ -254,7 +255,7 @@ class BLEInstanceBase
  * Return the instance of the vendor implementation of BLEInstanceBase.
  *
  * @important Contrary to its name, this function does not return a new instance
- * at eachcall. It rather act like an accessor to a singleton.
+ * at each call. It rather act like an accessor to a singleton.
  *
  * @important An implementation for this function must be provided by the vendor
  * library, otherwise there will be a linker error.

features/FEATURE_BLE/ble/BLETypes.h

@@ -30,7 +30,7 @@
 namespace ble {
 
 /**
- * Opaque reference to a connection
+ * Opaque reference to a connection.
  *
  * Internally a connection handle is an unsigned integer capable of holding a
  * pointer.
@@ -67,7 +67,7 @@ struct attribute_handle_range_t {
      * Equal operator for attribute_handle_range_t.
      *
      * @param[in] lhs Left hand side of the expression.
-     * @param[in] rhs Left hand side of the expression.
+     * @param[in] rhs Right hand side of the expression.
      *
      * @return true if lhs is equal to rhs and false otherwise.
      */
@@ -81,7 +81,7 @@ struct attribute_handle_range_t {
      * Not equal operator for attribute_handle_range_t.
      *
      * @param[in] lhs Left hand side of the expression.
-     * @param[in] rhs Left hand side of the expression.
+     * @param[in] rhs Right hand side of the expression.
      *
      * @return true if lhs is not equal to rhs and false otherwise.
      */

features/FEATURE_BLE/ble/CallChainOfFunctionPointersWithContext.h

@@ -72,7 +72,7 @@
  * }
  * @endcode
  *
- * @note memory allocation is used to add new function like object into the
+ * @note memory allocation is used to add new function like objects into the
  * call chain.
  *
  * @tparam ContextType Type of the parameter accepted by the callbacks hosted
@@ -270,11 +270,11 @@ class CallChainOfFunctionPointersWithContext :
      * @code
      * CallChainOfFunctionPointersWithContext<void *> chain;
      *
-     * if (chain) {
+     * if (!chain) {
      *   // Do something if the chain is empty.
      * }
      *
-     * if (!chain) {
+     * if (chain) {
      *   // Do something if the chain is not empty.
      * }
      * @endcode

features/FEATURE_BLE/ble/CharacteristicDescriptorDiscovery.h

@@ -100,7 +100,7 @@ class CharacteristicDescriptorDiscovery {
     /**
      * Characteristic descriptor discovered event handler.
      *
-     * As parameter it expect a pointer to a DiscoveryCallbackParams_t instance.
+     * As parameter it expects a pointer to a DiscoveryCallbackParams_t instance.
      *
      * @note The object passed in parameter will remain valid for the lifetime
      * of the callback. Memory for this object is owned by the BLE_API eventing
@@ -117,7 +117,7 @@ class CharacteristicDescriptorDiscovery {
     /**
      * Handler of Characteristic descriptor discovery ended event.
      *
-     * As parameter it expect a pointer to a TerminationCallbackParams_t instance.
+     * As parameter it expects a pointer to a TerminationCallbackParams_t instance.
      *
      * @note The object passed in parameter will remain valid for the lifetime
      * of the callback. Memory for this object is owned by the BLE_API eventing

features/FEATURE_BLE/ble/DiscoveredCharacteristic.h

@@ -39,13 +39,13 @@
  * Instances of this class are generated by the GattClient discovery procedure
  * initiated with GattClient::launchServiceDiscovery().
  *
- * It expose the main attributes of the discovered characteristic:
+ * It exposes the main attributes of the discovered characteristic:
  *   - The UUID of the characteristic, it can be retrieved by a call to the
  *     function getUUID(). This UUID is the type of the characteristic.
  *   - Attribute Handles of the characteristic are present as the triplet
  *     declaration handle, value handle and last handle. The value handle is
  *     used to read or write the content of the characteristic.
- *   - The properties contains the set of operations the characteristic can
+ *   - The properties contain the set of operations the characteristic can
  *     handle, for instance being read or written.
  *
  * It important to note that the value of the characteristic - if it is
@@ -144,7 +144,7 @@ class DiscoveredCharacteristic {
         /**
          * Return the value of the broadcast propertie.
          *
-         * @return if true the Server Characteristic Configuration Descriptor
+         * @return true if the Server Characteristic Configuration Descriptor
          * of the characteristic can be configured to broadcast the
          * characteristic value during broadcast procedure.
          *
@@ -261,8 +261,8 @@ class DiscoveredCharacteristic {
         /**
          * Not equal to operator for DiscoveredCharacteristic::Properties_t.
          *
-         * @param lhs The right hand side of the expression.
-         * @param rhs The left hand side of the expression.
+         * @param lhs The left hand side of the expression.
+         * @param rhs The right hand side of the expression.
          *
          * @return true if operands are not equals, false otherwise.
          */
@@ -310,7 +310,7 @@ class DiscoveredCharacteristic {
      * - where the read operation begin.
      *
      * @param[in] onRead Completion callback which will accept the response of
-     * the read request. The calback is copied, it is not necessary to keep it
+     * the read request. The callback is copied, it is not necessary to keep it
      * in memory after the call.
      *
      * @return BLE_ERROR_NONE if a read has been initiated.
@@ -492,7 +492,7 @@ class DiscoveredCharacteristic {
     /**
      * Return the last attribute handle of the characteristic definition.
      *
-     * The attribute layout of a characteristic definition is a follow:
+     * The attribute layout of a characteristic definition is as follows:
      *   - Declaration attribute (see #getDeclHandle)
      *   - Value attribute (see #getValueHandle)
      *   - Zero or more characteristic descriptors attribute.
@@ -503,7 +503,7 @@ class DiscoveredCharacteristic {
      *
      * @return The last handle of this characteristic definition.
      *
-     * @note This function is public for informative purposes..
+     * @note This function is public for informative purposes.
      */
     GattAttribute::Handle_t getLastHandle(void) const
     {

features/FEATURE_BLE/ble/DiscoveredService.h

@@ -34,7 +34,7 @@
  *
  * GATT Services are discovered on distant GATT servers by the discovery
  * procedure which can be initiated by calling
- * GattClient::launchServiceDiscovery() or GattClient::discoverServices() . The
+ * GattClient::launchServiceDiscovery() or GattClient::discoverServices(). The
  * discovery process will pass instances of this class to the callback handling
  * service discovered.
  *

features/FEATURE_BLE/ble/FunctionPointerWithContext.h

@@ -36,12 +36,12 @@
  * different even if conceptually they are very similar: Both primitives can be
  * copied, called and produce a result.
  *
- * To solve incompatibilities this class addapt freestanding and member function
+ * To solve incompatibilities this class adapt freestanding and member function
  * to a common interface. The interface chosen is similar to the freestanding
  * function pointers interface:
  *    - Copyable
  *    - Nullable
- *    - Callable .
+ *    - Callable
  *
  * This class also offers a mechanism to chain other instances to it. When an
  * instance is called, all the instances being part of the chain are called.
@@ -312,9 +312,9 @@ class FunctionPointerWithContext : public SafeBool<FunctionPointerWithContext<Co
 /**
  * Factory of adapted member function pointers.
  *
- * This factory eliminate the need to invoke the qualified constructor of
+ * This factory eliminates the need to invoke the qualified constructor of
  * FunctionPointerWithContext by using automatic type deduction of function
- * templates
+ * templates.
  *
  * @code
  *

features/FEATURE_BLE/ble/Gap.h

@@ -43,12 +43,12 @@ class GapAdvertisingData;
 /**
  * Define device discovery, connection and link management procedures.
  *
- * - Device discovery: A device can advertise nearby peer of its existence,
+ * - Device discovery: A device can advertise nearby peers of its existence,
  * identity and capabilities. Similarly a device can scan its environment to
- * find advertising peers. The informations acquired during the scan help to
+ * find advertising peers. The information acquired during the scan helps to
  * identify peers and understand their use. A scanner may acquire more information
- * about an advertising peer by sending a scan request. If the peer accept scan
- * request it may reply with additional information about its state.
+ * about an advertising peer by sending a scan request. If the peer accepts scan
+ * requests it may reply with additional information about its state.
  *
  * - Connection: A bluetooth device can establish a connection to a connectable
  * advertising peer. Once the connection is established both devices can
@@ -75,12 +75,12 @@ class GapAdvertisingData;
  *
  * @par Advertising
  *
- * Advertising consist of broadcasting at a regular interval a small amount of
+ * Advertising consists of broadcasting at a regular interval a small amount of
  * data containing valuable informations about the device. These packets may be
  * scanned by peer devices listening on BLE advertising channels.
  *
- * Scanner may also request additional information from a device advertising by
- * sending a scan request. If the broadcaster accept scan request it can reply
+ * Scanners may also request additional information from a device advertising by
+ * sending a scan request. If the broadcaster accepts scan requests it can reply
  * with a scan response packet containing additional information.
  *
  * @code
@@ -192,7 +192,7 @@ class GapAdvertisingData;
  * }
  *
  * // register connection event handler which will be invoked whether the device
- * // act as a central or a peripheral
+ * // acts as a central or a peripheral
  * gap.onConnection(when_connected);
  * @endcode
  *
@@ -515,7 +515,7 @@ class Gap {
          * connection.
          *
          * It shall be greater than or equal to minConnectionInterval. This
-         * value is in unit of 1,25ms and shall be in the range [0x0006 : 0x0C80].
+         * value is in unit of 1.25ms and shall be in the range [0x0006 : 0x0C80].
          */
         uint16_t maxConnectionInterval;
 
@@ -549,7 +549,7 @@ class Gap {
      *
      * @note broadcaster and scanner roles are not expressed in BLE API.
      *
-     * @important A device can fullfill concurrently different roles.
+     * @important A device can fullfil different roles concurrently.
      */
     enum Role_t {
         /**
@@ -1101,7 +1101,7 @@ class Gap {
      * Update connection parameters of an existing connection.
      *
      * In the central role this will initiate a Link Layer connection parameter
-     * update procedure. In the peripheral role,  this will send the corresponding
+     * update procedure. In the peripheral role, this will send the corresponding
      * L2CAP request and wait for the central to perform the procedure.
      *
      * @param[in] handle Connection Handle.
@@ -1263,7 +1263,7 @@ class Gap {
      *
      * @param[in,out] whitelist Define the whitelist instance which will be used
      * to store the whitelist requested. In input memory shall be provisioned by
-     * the caller. .
+     * the caller.
      *
      * @return BLE_ERROR_NONE if the implementation's whitelist was successfully
      * copied into the supplied reference.
@@ -1485,7 +1485,7 @@ class Gap {
      * A call to this function is equivalent to:
      *
      * @code
-     * Gap& gap;
+     * Gap ⪆
      *
      * GapAdvertisingData payload = gap.getAdvertisingPayload();
      * payload.addFlags(flags);
@@ -1519,7 +1519,7 @@ class Gap {
      * A call to this function is equivalent to:
      *
      * @code
-     * Gap& gap;
+     * Gap ⪆
      *
      * GapAdvertisingData payload = gap.getAdvertisingPayload();
      * payload.addAppearance(app);
@@ -1553,7 +1553,7 @@ class Gap {
      * A call to this function is equivalent to:
      *
      * @code
-     * Gap& gap;
+     * Gap ⪆
      *
      * GapAdvertisingData payload = gap.getAdvertisingPayload();
      * payload.addTxPower(power);
@@ -1587,7 +1587,7 @@ class Gap {
      * A call to this function is equivalent to:
      *
      * @code
-     * Gap& gap;
+     * Gap ⪆
      *
      * GapAdvertisingData payload = gap.getAdvertisingPayload();
      * payload.addData(type, data, len);
@@ -1630,7 +1630,7 @@ class Gap {
      * A call to this function is equivalent to:
      *
      * @code
-     * Gap& gap;
+     * Gap ⪆
      *
      * GapAdvertisingData payload = gap.getAdvertisingPayload();
      * payload.updateData(type, data, len);
@@ -1784,8 +1784,8 @@ class Gap {
     /**
      * Set the interval parameter used during scanning procedures.
      *
-     * @param[in] interval interval in ms between the start of two consecutive
-     * scan window.That value shall be greater or equal to the scan window value.
+     * @param[in] interval Interval in ms between the start of two consecutive
+     * scan windows. That value shall be greater or equal to the scan window value.
      * The maximum allowed value is 10.24ms.
      *
      * @return BLE_ERROR_NONE if the scan interval was correctly set.

features/FEATURE_BLE/ble/GapAdvertisingData.h

@@ -53,7 +53,7 @@
  *
  * @code
  *
- * Gap& gap;
+ * Gap ⪆
  *
  * static const uint8_t device_name[] = "HRM";
  *

features/FEATURE_BLE/ble/GapAdvertisingParams.h

@@ -35,7 +35,7 @@
  *   - Time interval between advertisement. It can be set at construction time,
  *     updated by setInterval() and obtained from getInterval().
  *   - Duration of the advertising process. As others it can be set at
- *     construction time, modified by setTimeout() retrieved by getTimeout().
+ *     construction time, modified by setTimeout() and retrieved by getTimeout().
  */
 class GapAdvertisingParams {
 public:

features/FEATURE_BLE/ble/GapScanningParams.h

@@ -29,9 +29,9 @@
  *
  * The scan procedure is defined by four distinct parameters:
  *    - Scan window: Period during which the scanner listen to advertising
- *      channels. That value shall be in the 2.5ms to 10.24s. this value can be
- *      set at construction time, updated by calling setWindow() and retrieved
- *      by invoking getWindow().
+ *      channels. That value shall be in the range 2.5ms to 10.24s. This value
+ *      can be set at construction time, updated by calling setWindow() and
+ *      retrieved by invoking getWindow().
  *
  *    - Scan interval: interval between the start of two consecutive scan window.
  *      That value shall be greater or equal to the scan window value. The
@@ -47,8 +47,8 @@
  *      or connectable advertiser. Advertisers may respond to the scan request
  *      by a scan response containing the scan response payload. If not set then
  *      the scanner does not send any request. This flag is set at construction
- *      time, may be updated with the help of setActiveScanning() and get by
- *      getActiveScanning().
+ *      time, may be updated with the help of setActiveScanning() and retrieved
+ *      by getActiveScanning().
  *
  * @note If the scan windows duration is equal to the scan interval then the
  * device should listen continuously during the scan procedure.

features/FEATURE_BLE/ble/GattCallbackParamTypes.h

@@ -32,8 +32,8 @@
  * received a write response.
  *
  * @important The fields offset, len and data are only populated by the
- * GattServer when it receive a write request. Those fields shall not be used
- * by callbacks attached to the GattClient.
+ * GattServer when it has received a write request. Those fields shall not be
+ * used by callbacks attached to the GattClient.
  *
  * @important The fields status and error_code are only populated by the
  * GattClient when it has received a write response. Those fields shall not be