Diff: ble/BLE.h

Revision:

1142:a358d0d20f62

Parent:

1141:510f5d2d2732

Child:

1144:249843612f87

--- a/ble/BLE.h	Wed Apr 06 19:14:06 2016 +0100
+++ b/ble/BLE.h	Wed Apr 06 19:14:07 2016 +0100
@@ -68,7 +68,7 @@
 
     /**
      * Initialize the BLE controller. This should be called before using
-     * anything else in the BLE_API.
+     * anything else in the BLE API.
      *
      * init() hands control to the underlying BLE module to accomplish
      * initialization. This initialization may tacitly depend on other hardware
@@ -139,38 +139,69 @@
      *
      * @return  A pointer to a const string representing the version.
      *
-     * @note: The string returned is owned by BLE_API.
+     * @note The string returned is owned by BLE API.
      */
     const char *getVersion(void);
 
-    /*
-     * Accessors to GAP. Please refer to Gap.h. All GAP related functionality requires
+    /**
+     * Accessor to Gap. All Gap related functionality requires
      * going through this accessor.
+     *
+     * @return A reference to a Gap object associated to this BLE instance.
+     */
+    Gap &gap();
+
+    /**
+     * A const alternative to gap().
+     *
+     * @return A const reference to a Gap object associated to this BLE instance.
      */
     const Gap &gap() const;
-    Gap &gap();
 
-    /*
-     * Accessors to GATT Server. Please refer to GattServer.h. All GATTServer related
-     * functionality requires going through this accessor.
+    /**
+     * Accessor to GattServer. All GattServer related functionality requires
+     * going through this accessor.
+     *
+     * @return A reference to a GattServer object associated to this BLE instance.
      */
-    const GattServer& gattServer() const;
     GattServer& gattServer();
 
-    /*
-     * Accessors to GATT Client. Please refer to GattClient.h. All GATTClient related
-     * functionality requires going through this accessor.
+    /**
+     * A const alternative to gattServer().
+     *
+     * @return A const reference to a GattServer object associated to this BLE instance.
      */
-    const GattClient& gattClient() const;
+    const GattServer& gattServer() const;
+
+    /**
+     * Accessors to GattClient. All GattClient related functionality requires going
+     * through this accessor.
+     *
+     * @return A reference to a GattClient object associated to this BLE instance.
+     */
     GattClient& gattClient();
 
-    /*
-     * Accessors to Security Manager. Please refer to SecurityManager.h. All
-     * SecurityManager related functionality requires going through this
-     * accessor.
+    /**
+     * A const alternative to gattClient().
+     *
+     * @return A const reference to a GattClient object associated to this BLE instance.
+     */
+    const GattClient& gattClient() const;
+
+    /**
+     * Accessors to SecurityManager. All SecurityManager related functionality requires
+     * going through this accessor.
+     *
+     * @return A reference to a SecurityManager object associated to this BLE instance.
+     */
+    SecurityManager& securityManager();
+
+    /**
+     * A const alternative to securityManager().
+     *
+     * @return A const reference to a SecurityManager object associated to this BLE instance.
      */
     const SecurityManager& securityManager() const;
-    SecurityManager& securityManager();
 
     /**
      * Yield control to the BLE stack or to other tasks waiting for events. This
@@ -182,10 +213,19 @@
     void waitForEvent(void);
 
 public:
+    /**
+     * The value of the BLE::InstanceID_t for the default BLE instance.
+     */
     static const InstanceID_t DEFAULT_INSTANCE = 0;
 #ifndef YOTTA_CFG_BLE_INSTANCES_COUNT
+    /**
+     * The number of permitted BLE instances for the application.
+     */
     static const InstanceID_t NUM_INSTANCES = 1;
 #else
+    /**
+     * The number of permitted BLE instances for the application.
+     */
     static const InstanceID_t NUM_INSTANCES = YOTTA_CFG_BLE_INSTANCES_COUNT;
 #endif
 
@@ -193,14 +233,14 @@
      * Get a reference to the BLE singleton corresponding to a given interface.
      * There is a static array of BLE singletons.
      *
-     * @note: Calling Instance() is preferred over constructing a BLE object
+     * @note Calling Instance() is preferred over constructing a BLE object
      * directly, as it returns references to singletons.
      *
      * @param[in] id
      *              Instance-ID. This should be less than NUM_INSTANCES
      *              for the returned BLE singleton to be useful.
      *
-     * @return a reference to a single object.
+     * @return A reference to a single object.
      */
     static BLE &Instance(InstanceID_t id = DEFAULT_INSTANCE);
 
@@ -235,7 +275,7 @@
      * Set the BTLE MAC address and type.
      * @return BLE_ERROR_NONE on success.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.setAddress(...) should be replaced with
      * ble.gap().setAddress(...).
@@ -245,10 +285,10 @@
     }
 
     /**
-     * Fetch the BTLE MAC address and type.
+     * Fetch the Bluetooth Low Energy MAC address and type.
      * @return BLE_ERROR_NONE on success.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.getAddress(...) should be replaced with
      * ble.gap().getAddress(...).
@@ -260,7 +300,7 @@
     /**
      * Set the GAP advertising mode to use for this device.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.setAdvertisingType(...) should be replaced with
      * ble.gap().setAdvertisingType(...).
@@ -280,16 +320,16 @@
      *              This field must be set to 0 if connectionMode is equal
      *              to ADV_CONNECTABLE_DIRECTED.
      *
-     * @note: Decreasing this value allows central devices to detect a
+     * @note Decreasing this value allows central devices to detect a
      * peripheral faster, at the expense of more power being used by the radio
      * due to the higher data transmit rate.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.setAdvertisingInterval(...) should be replaced with
      * ble.gap().setAdvertisingInterval(...).
      *
-     * @note: [WARNING] This API previously used 0.625ms as the unit for its
+     * @note WARNING: This API previously used 0.625ms as the unit for its
      * 'interval' argument. That required an explicit conversion from
      * milliseconds using Gap::MSEC_TO_GAP_DURATION_UNITS(). This conversion is
      * no longer required as the new units are milliseconds. Any application
@@ -302,7 +342,7 @@
     /**
      * @return Minimum Advertising interval in milliseconds.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.getMinAdvertisingInterval(...) should be replaced with
      * ble.gap().getMinAdvertisingInterval(...).
@@ -314,7 +354,7 @@
     /**
      * @return Minimum Advertising interval in milliseconds for non-connectible mode.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.getMinNonConnectableAdvertisingInterval(...) should be replaced with
      * ble.gap().getMinNonConnectableAdvertisingInterval(...).
@@ -326,7 +366,7 @@
     /**
      * @return Maximum Advertising interval in milliseconds.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.getMaxAdvertisingInterval(...) should be replaced with
      * ble.gap().getMaxAdvertisingInterval(...).
@@ -340,7 +380,7 @@
      *              Advertising timeout (in seconds) between 0x1 and 0x3FFF (1
      *              and 16383). Use 0 to disable the advertising timeout.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.setAdvertisingTimeout(...) should be replaced with
      * ble.gap().setAdvertisingTimeout(...).
@@ -355,7 +395,7 @@
      * directly; there are other APIs to tweak advertisement parameters
      * individually (see above).
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.setAdvertisingParams(...) should be replaced with
      * ble.gap().setAdvertisingParams(...).
@@ -368,7 +408,7 @@
      * @return  Read back advertising parameters. Useful for storing and
      *          restoring parameters rapidly.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.getAdvertisingParams(...) should be replaced with
      * ble.gap().getAdvertisingParams(...).
@@ -388,7 +428,7 @@
      *              GapAdvertisingData::Flags for valid flags. Multiple
      *              flags may be specified in combination.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.accumulateAdvertisingPayload(flags) should be replaced with
      * ble.gap().accumulateAdvertisingPayload(flags).
@@ -406,7 +446,7 @@
      * @param[in] app
      *              The appearance of the peripheral.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.accumulateAdvertisingPayload(appearance) should be replaced with
      * ble.gap().accumulateAdvertisingPayload(appearance).
@@ -421,11 +461,11 @@
      * as an additional 31 bytes if the advertising payload is too
      * small.
      *
-     * @param[in] app
+     * @param[in] power
      *              The max transmit power to be used by the controller. This
      *              is only a hint.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with
      * ble.gap().accumulateAdvertisingPayloadTxPower(txPower).
@@ -444,7 +484,7 @@
      * @param  data Data bytes.
      * @param  len  Data length.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.accumulateAdvertisingPayload(...) should be replaced with
      * ble.gap().accumulateAdvertisingPayload(...).
@@ -458,7 +498,7 @@
      * underlying stack. It would be uncommon for this API to be used directly;
      * there are other APIs to build an advertisement payload (see above).
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.setAdvertisingData(...) should be replaced with
      * ble.gap().setAdvertisingPayload(...).
@@ -471,7 +511,7 @@
      * @return  Read back advertising data. Useful for storing and
      *          restoring payload.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.getAdvertisingData(...) should be replaced with
      * ble.gap().getAdvertisingPayload()(...).
@@ -485,7 +525,7 @@
      * accumulateAdvertisingPayload(). This automatically propagates the re-
      * initialized advertising payload to the underlying stack.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.clearAdvertisingPayload(...) should be replaced with
      * ble.gap().clearAdvertisingPayload(...).
@@ -517,7 +557,7 @@
      * @param[in] data Data bytes.
      * @param[in] len  Data length.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.accumulateScanResponse(...) should be replaced with
      * ble.gap().accumulateScanResponse(...).
@@ -530,7 +570,7 @@
      * Reset any scan response prepared from prior calls to
      * accumulateScanResponse().
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.clearScanResponse(...) should be replaced with
      * ble.gap().clearScanResponse(...).
@@ -542,7 +582,7 @@
     /**
      * Start advertising.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.startAdvertising(...) should be replaced with
      * ble.gap().startAdvertising(...).
@@ -554,7 +594,7 @@
     /**
      * Stop advertising.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.stopAdvertising(...) should be replaced with
      * ble.gap().stopAdvertising(...).
@@ -585,9 +625,9 @@
      * Once the scanning parameters have been configured, scanning can be
      * enabled by using startScan().
      *
-     * @note: The scan interval and window are recommendations to the BLE stack.
+     * @note The scan interval and window are recommendations to the BLE stack.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.setScanParams(...) should be replaced with
      * ble.gap().setScanParams(...).
@@ -614,7 +654,7 @@
      * Once the scanning parameters have been configured, scanning can be
      * enabled by using startScan().
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.setScanInterval(interval) should be replaced with
      * ble.gap().setScanInterval(interval).
@@ -638,7 +678,7 @@
      * Once the scanning parameters have been configured, scanning can be
      * enabled by using startScan().
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.setScanWindow(window) should be replaced with
      * ble.gap().setScanWindow(window).
@@ -662,9 +702,9 @@
      * Once the scanning parameters have been configured, scanning can be
      * enabled by using startScan().
      *
-     * @note: The scan interval and window are recommendations to the BLE stack.
+     * @note The scan interval and window are recommendations to the BLE stack.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.setScanTimeout(...) should be replaced with
      * ble.gap().setScanTimeout(...).
@@ -682,7 +722,7 @@
      * Once the scanning parameters have been configured, scanning can be
      * enabled by using startScan().
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.setActiveScan(...) should be replaced with
      * ble.gap().setActiveScanning(...).
@@ -700,7 +740,7 @@
      *              receiving every advertisement report. This can be passed in
      *              as NULL, in which case scanning may not be enabled at all.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.startScan(callback) should be replaced with
      * ble.gap().startScan(callback).
@@ -712,7 +752,7 @@
     /**
      * Same as above, but this takes an (object, method) pair for a callback.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.startScan(callback) should be replaced with
      * ble.gap().startScan(object, callback).
@@ -725,7 +765,7 @@
      *
      * @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.stopScan() should be replaced with
      * ble.gap().stopScan().
@@ -748,7 +788,7 @@
      *     successfully. The onConnection callback (if set) is invoked upon
      *     a connection event.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.connect(...) should be replaced with
      * ble.gap().connect(...).
@@ -781,12 +821,12 @@
      * @param  reason
      *           The reason for disconnection; sent back to the peer.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.disconnect(reason) should be replaced with
      * ble.gap().disconnect(reason).
      *
-     * @note: This version of disconnect() doesn't take a connection handle. It
+     * @note This version of disconnect() doesn't take a connection handle. It
      * works reliably only for stacks that are limited to a single
      * connection. This API should be considered *deprecated* in favour of the
      * alternative, which takes a connection handle. It will be dropped in the future.
@@ -796,10 +836,10 @@
     }
 
     /**
-     * Returns the current GAP state of the device using a bitmask that
+     * Returns the current Gap state of the device using a bitmask that
      * describes whether the device is advertising or connected.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.getGapState() should be replaced with
      * ble.gap().getState().
@@ -820,7 +860,7 @@
      * @return BLE_ERROR_NONE if the parameters were successfully filled into
      * the given structure pointed to by params.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.getPreferredConnectionParams() should be replaced with
      * ble.gap().getPreferredConnectionParams().
@@ -837,7 +877,7 @@
      * @param[in] params
      *               The structure containing the desired parameters.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.setPreferredConnectionParams() should be replaced with
      * ble.gap().setPreferredConnectionParams().
@@ -856,7 +896,7 @@
      *              Pointer to desired connection parameters. If NULL is provided on a peripheral role,
      *              the parameters in the PPCP characteristic of the GAP service will be used instead.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.updateConnectionParams() should be replaced with
      * ble.gap().updateConnectionParams().
@@ -866,11 +906,11 @@
     }
 
     /**
-     * Set the device name characteristic in the GAP service.
+     * Set the device name characteristic in the Gap service.
      * @param[in] deviceName
      *              The new value for the device-name. This is a UTF-8 encoded, <b>NULL-terminated</b> string.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.setDeviceName() should be replaced with
      * ble.gap().setDeviceName().
@@ -880,14 +920,14 @@
     }
 
     /**
-     * Get the value of the device name characteristic in the GAP service.
+     * Get the value of the device name characteristic in the Gap service.
      * @param[out]    deviceName
      *                  Pointer to an empty buffer where the UTF-8 *non NULL-
      *                  terminated* string will be placed. Set this
      *                  value to NULL in order to obtain the deviceName-length
      *                  from the 'length' parameter.
      *
-     * @param[in/out] lengthP
+     * @param[in,out] lengthP
      *                  (on input) Length of the buffer pointed to by deviceName;
      *                  (on output) the complete device name length (without the
      *                     null terminator).
@@ -897,7 +937,7 @@
      *     number of bytes actually returned in deviceName. The application may
      *     use this information to retry with a suitable buffer size.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.getDeviceName() should be replaced with
      * ble.gap().getDeviceName().
@@ -907,11 +947,11 @@
     }
 
     /**
-     * Set the appearance characteristic in the GAP service.
+     * Set the appearance characteristic in the Gap service.
      * @param[in] appearance
      *              The new value for the device-appearance.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.setAppearance() should be replaced with
      * ble.gap().setAppearance().
@@ -921,11 +961,11 @@
     }
 
     /**
-     * Get the appearance characteristic in the GAP service.
-     * @param[out] appearance
+     * Get the appearance characteristic in the Gap service.
+     * @param[out] appearanceP
      *               The new value for the device-appearance.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.getAppearance() should be replaced with
      * ble.gap().getAppearance().
@@ -938,7 +978,7 @@
      * Set the radio's transmit power.
      * @param[in] txPower Radio transmit power in dBm.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.setTxPower() should be replaced with
      * ble.gap().setTxPower().
@@ -955,7 +995,7 @@
      * @param[out] countP
      *                 Out parameter to receive the array's size.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call to
      * ble.getPermittedTxPowerValues() should be replaced with
      * ble.gap().getPermittedTxPowerValues().
@@ -968,7 +1008,7 @@
      * Add a service declaration to the local server ATT table. Also add the
      * characteristics contained within.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from GattServer directly. A former call
      * to ble.addService() should be replaced with
      * ble.gattServer().addService().
@@ -983,7 +1023,7 @@
      *                  Attribute handle for the value attribute of the characteristic.
      * @param[out]    buffer
      *                  A buffer to hold the value being read.
-     * @param[in/out] lengthP
+     * @param[in,out] lengthP
      *                  Length of the buffer being supplied. If the attribute
      *                  value is longer than the size of the supplied buffer,
      *                  this variable will return the total attribute value length
@@ -992,7 +1032,7 @@
      *
      * @return BLE_ERROR_NONE if a value was read successfully into the buffer.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from GattServer directly. A former call
      * to ble.readCharacteristicValue() should be replaced with
      * ble.gattServer().read().
@@ -1009,7 +1049,7 @@
      *                  Attribute handle for the value attribute of the characteristic.
      * @param[out]    buffer
      *                  A buffer to hold the value being read.
-     * @param[in/out] lengthP
+     * @param[in,out] lengthP
      *                  Length of the buffer being supplied. If the attribute
      *                  value is longer than the size of the supplied buffer,
      *                  this variable will return the total attribute value length
@@ -1022,7 +1062,7 @@
      *     parameter to allow fetches for connection-specific multivalued
      *     attributes (such as the CCCDs).
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from GattServer directly. A former call
      * to ble.readCharacteristicValue() should be replaced with
      * ble.gattServer().read().
@@ -1049,7 +1089,7 @@
      *
      * @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from GattServer directly. A former call
      * to ble.updateCharacteristicValue() should be replaced with
      * ble.gattServer().write().
@@ -1083,7 +1123,7 @@
      *
      * @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from GattServer directly. A former call
      * to ble.updateCharacteristicValue() should be replaced with
      * ble.gattServer().write().
@@ -1111,7 +1151,7 @@
      *
      * @return BLE_ERROR_NONE on success.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from SecurityManager directly. A former
      * call to ble.initializeSecurity(...) should be replaced with
      * ble.securityManager().init(...).
@@ -1131,7 +1171,7 @@
      *
      * @return BLE_SUCCESS or appropriate error code indicating the reason of failure.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from SecurityManager directly. A former
      * call to ble.getLinkSecurity(...) should be replaced with
      * ble.securityManager().getLinkSecurity(...).
@@ -1148,7 +1188,7 @@
      * @retval BLE_ERROR_INVALID_STATE    If the API is called without module initialization or
      *                                    application registration.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from SecurityManager directly. A former
      * call to ble.purgeAllBondingState() should be replaced with
      * ble.securityManager().purgeAllBondingState().
@@ -1161,7 +1201,7 @@
      * Set up a callback for timeout events. Refer to Gap::TimeoutSource_t for
      * possible event types.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call
      * to ble.onTimeout(callback) should be replaced with
      * ble.gap().onTimeout(callback).
@@ -1173,7 +1213,7 @@
     /**
      * Set up a callback for connection events. Refer to Gap::ConnectionEventCallback_t.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call
      * to ble.onConnection(callback) should be replaced with
      * ble.gap().onConnection(callback).
@@ -1185,7 +1225,7 @@
     /**
      * Append to a chain of callbacks to be invoked upon GAP disconnection.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call
      * to ble.onDisconnection(callback) should be replaced with
      * ble.gap().onDisconnection(callback).
@@ -1194,6 +1234,15 @@
         gap().onDisconnection(disconnectionCallback);
     }
 
+    /**
+     * The same as onDisconnection(), but allows an object reference and member function
+     * to be added to the chain of callbacks.
+     *
+     * @note This API is now *deprecated* and will be dropped in the future.
+     * You should use the parallel API from Gap directly. A former call
+     * to ble.onDisconnection(callback) should be replaced with
+     * ble.gap().onDisconnection(callback).
+     */
     template<typename T>
     void onDisconnection(T *tptr, void (T::*mptr)(const Gap::DisconnectionCallbackParams_t*)) {
         gap().onDisconnection(tptr, mptr);
@@ -1215,7 +1264,7 @@
      *          The application handler to be invoked in response to a radio
      *          ACTIVE/INACTIVE event.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from Gap directly. A former call
      * to ble.onRadioNotification(...) should be replaced with
      * ble.gap().onRadioNotification(...).
@@ -1228,14 +1277,14 @@
      * Add a callback for the GATT event DATA_SENT (which is triggered when
      * updates are sent out by GATT in the form of notifications).
      *
-     * @note: It is possible to chain together multiple onDataSent callbacks
+     * @note It is possible to chain together multiple onDataSent callbacks
      * (potentially from different modules of an application) to receive updates
      * to characteristics.
      *
-     * @note: It is also possible to set up a callback into a member function of
+     * @note It is also possible to set up a callback into a member function of
      * some object.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from GattServer directly. A former call
      * to ble.onDataSent(...) should be replaced with
      * ble.gattServer().onDataSent(...).
@@ -1243,6 +1292,16 @@
     void onDataSent(void (*callback)(unsigned count)) {
         gattServer().onDataSent(callback);
     }
+
+    /**
+     * The same as onDataSent(), but allows an object reference and member function
+     * to be added to the chain of callbacks.
+     *
+     * @note This API is now *deprecated* and will be dropped in the future.
+     * You should use the parallel API from GattServer directly. A former call
+     * to ble.onDataSent(...) should be replaced with
+     * ble.gattServer().onDataSent(...).
+     */
     template <typename T> void onDataSent(T * objPtr, void (T::*memberPtr)(unsigned count)) {
         gattServer().onDataSent(objPtr, memberPtr);
     }
@@ -1254,15 +1313,15 @@
      * For a Central, this callback is triggered when a response is received for
      * a write request.
      *
-     * @note: It is possible to chain together multiple onDataWritten callbacks
+     * @note It is possible to chain together multiple onDataWritten callbacks
      * (potentially from different modules of an application) to receive updates
      * to characteristics. Many services, such as DFU and UART, add their own
      * onDataWritten callbacks behind the scenes to trap interesting events.
      *
-     * @note: It is also possible to set up a callback into a member function of
+     * @note It is also possible to set up a callback into a member function of
      * some object.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from GattServer directly. A former call
      * to ble.onDataWritten(...) should be replaced with
      * ble.gattServer().onDataWritten(...).
@@ -1270,6 +1329,16 @@
     void onDataWritten(void (*callback)(const GattWriteCallbackParams *eventDataP)) {
         gattServer().onDataWritten(callback);
     }
+
+    /**
+     * The same as onDataWritten(), but allows an object reference and member function
+     * to be added to the chain of callbacks.
+     *
+     * @note This API is now *deprecated* and will be dropped in the future.
+     * You should use the parallel API from GattServer directly. A former call
+     * to ble.onDataWritten(...) should be replaced with
+     * ble.gattServer().onDataWritten(...).
+     */
     template <typename T> void onDataWritten(T * objPtr, void (T::*memberPtr)(const GattWriteCallbackParams *context)) {
         gattServer().onDataWritten(objPtr, memberPtr);
     }
@@ -1278,22 +1347,22 @@
      * Set up a callback to be invoked on the peripheral when an attribute is
      * being read by a remote client.
      *
-     * @note: This functionality may not be available on all underlying stacks.
+     * @note This functionality may not be available on all underlying stacks.
      * You could use GattCharacteristic::setReadAuthorizationCallback() as an
      * alternative.
      *
-     * @note: It is possible to chain together multiple onDataRead callbacks
+     * @note It is possible to chain together multiple onDataRead callbacks
      * (potentially from different modules of an application) to receive updates
      * to characteristics. Services may add their own onDataRead callbacks
      * behind the scenes to trap interesting events.
      *
-     * @note: It is also possible to set up a callback into a member function of
+     * @note It is also possible to set up a callback into a member function of
      * some object.
      *
      * @return BLE_ERROR_NOT_IMPLEMENTED if this functionality isn't available;
      *         else BLE_ERROR_NONE.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from GattServer directly. A former call
      * to ble.onDataRead(...) should be replaced with
      * ble.gattServer().onDataRead(...).
@@ -1301,6 +1370,16 @@
     ble_error_t onDataRead(void (*callback)(const GattReadCallbackParams *eventDataP)) {
         return gattServer().onDataRead(callback);
     }
+
+    /**
+     * The same as onDataRead(), but allows an object reference and member function
+     * to be added to the chain of callbacks.
+     *
+     * @note This API is now *deprecated* and will be dropped in the future.
+     * You should use the parallel API from GattServer directly. A former call
+     * to ble.onDataRead(...) should be replaced with
+     * ble.gattServer().onDataRead(...).
+     */
     template <typename T> ble_error_t onDataRead(T * objPtr, void (T::*memberPtr)(const GattReadCallbackParams *context)) {
         return gattServer().onDataRead(objPtr, memberPtr);
     }
@@ -1309,7 +1388,7 @@
      * Set up a callback for when notifications or indications are enabled for a
      * characteristic on the local GattServer.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from GattServer directly. A former call
      * to ble.onUpdatesEnabled(callback) should be replaced with
      * ble.gattServer().onUpdatesEnabled(callback).
@@ -1322,7 +1401,7 @@
      * Set up a callback for when notifications or indications are disabled for a
      * characteristic on the local GattServer.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from GattServer directly. A former call
      * to ble.onUpdatesEnabled(callback) should be replaced with
      * ble.gattServer().onUpdatesEnabled(callback).
@@ -1335,7 +1414,7 @@
      * Set up a callback for when the GATT server receives a response for an
      * indication event sent previously.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from GattServer directly. A former call
      * to ble.onConfirmationReceived(callback) should be replaced with
      * ble.gattServer().onConfirmationReceived(callback).
@@ -1351,7 +1430,7 @@
      * security request: bool allowBonding, bool requireMITM, and
      * SecurityIOCapabilities_t.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from SecurityManager directly. A former
      * call to ble.onSecuritySetupInitiated(callback) should be replaced with
      * ble.securityManager().onSecuritySetupInitiated(callback).
@@ -1366,7 +1445,7 @@
      * devices. The callback is passed in the success/failure status of the
      * security setup procedure.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from SecurityManager directly. A former
      * call to ble.onSecuritySetupCompleted(callback) should be replaced with
      * ble.securityManager().onSecuritySetupCompleted(callback).
@@ -1383,7 +1462,7 @@
      * or both sides. The callback is passed in a SecurityManager::SecurityMode_t according
      * to the level of security in effect for the secured link.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from SecurityManager directly. A former
      * call to ble.onLinkSecured(callback) should be replaced with
      * ble.securityManager().onLinkSecured(callback).
@@ -1396,7 +1475,7 @@
      * Set up a callback for successful bonding, meaning that link-specific security
      * context is stored persistently for a peer device.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from SecurityManager directly. A former
      * call to ble.onSecurityContextStored(callback) should be replaced with
      * ble.securityManager().onSecurityContextStored(callback).
@@ -1412,7 +1491,7 @@
      * a passkey (or PIN) to authenticate the connection
      * attempt.
      *
-     * @note: This API is now *deprecated* and will be dropped in the future.
+     * @note This API is now *deprecated* and will be dropped in the future.
      * You should use the parallel API from SecurityManager directly. A former
      * call to ble.onPasskeyDisplay(callback) should be replaced with
      * ble.securityManager().onPasskeyDisplay(callback).