Diff: ble/BLE.h

Revision:

1155:e28c7aac64ab

Parent:

1144:249843612f87

Child:

1156:e1ea38b576c6

diff -r 702de9e6b049 -r e28c7aac64ab ble/BLE.h
--- a/ble/BLE.h	Wed Apr 06 19:14:32 2016 +0100
+++ b/ble/BLE.h	Wed Apr 06 19:14:34 2016 +0100
@@ -40,7 +40,7 @@
 class BLE
 {
 public:
-    typedef unsigned InstanceID_t; /**< The type returned by BLE::getInstanceID(). */
+    typedef unsigned InstanceID_t; /** The type returned by BLE::getInstanceID(). */
 
     /**
      * The context provided to init-completion-callbacks (see init() below).
@@ -53,8 +53,8 @@
      *             the error value is implementation specific.
      */
     struct InitializationCompleteCallbackContext {
-        BLE&        ble;   /**< Reference to the BLE object that has been initialized */
-        ble_error_t error; /**< Error status of the initialization. It is set to BLE_ERROR_NONE if initialization completed successfully. */
+        BLE&        ble;   /* Reference to the BLE object that has been initialized */
+        ble_error_t error; /* Error status of the initialization. It is set to BLE_ERROR_NONE if initialization completed successfully. */
     };
 
     /**
@@ -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
@@ -138,70 +138,38 @@
      * This call allows the application to get the BLE stack version information.
      *
      * @return  A pointer to a const string representing the version.
-     *
-     * @note The string returned is owned by BLE API.
+     *          Note: The string is owned by BLE_API.
      */
     const char *getVersion(void);
 
-    /**
-     * Accessor to Gap. All Gap related functionality requires
+    /*
+     * Accessors to GAP. Please refer to Gap.h. 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();
 
-    /**
-     * Accessor to GattServer. All GattServer related functionality requires
-     * going through this accessor.
-     *
-     * @return A reference to a GattServer object associated to this BLE instance.
-     */
-    GattServer& gattServer();
-
-    /**
-     * A const alternative to gattServer().
-     *
-     * @return A const reference to a GattServer object associated to this BLE instance.
+    /*
+     * Accessors to GATT Server. Please refer to GattServer.h. All GATTServer related
+     * functionality requires going through this accessor.
      */
     const GattServer& gattServer() const;
+    GattServer& gattServer();
 
-    /**
-     * 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();
-
-    /**
-     * A const alternative to gattClient().
-     *
-     * @return A const reference to a GattClient object associated to this BLE instance.
+    /*
+     * Accessors to GATT Client. Please refer to GattClient.h. All GATTClient related
+     * functionality requires going through this accessor.
      */
     const GattClient& gattClient() const;
+    GattClient& gattClient();
 
-    /**
-     * 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.
+    /*
+     * Accessors to Security Manager. Please refer to SecurityManager.h. All
+     * SecurityManager related functionality requires going through this
+     * accessor.
      */
     const SecurityManager& securityManager() const;
+    SecurityManager& securityManager();
 
     /**
      * Yield control to the BLE stack or to other tasks waiting for events. This
@@ -213,19 +181,10 @@
     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
 
@@ -233,14 +192,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);
 
@@ -275,21 +234,23 @@
      * Set the BTLE MAC address and type.
      * @return BLE_ERROR_NONE on success.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.setAddress(...) should be replaced with
-     *             ble.gap().setAddress(...).
+     * @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(...).
      */
     ble_error_t setAddress(BLEProtocol::AddressType_t type, const BLEProtocol::AddressBytes_t address) {
         return gap().setAddress(type, address);
     }
 
     /**
-     * Fetch the Bluetooth Low Energy MAC address and type.
+     * Fetch the BTLE MAC address and type.
      * @return BLE_ERROR_NONE on success.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.getAddress(...) should be replaced with
-     *             ble.gap().getAddress(...).
+     * @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(...).
      */
     ble_error_t getAddress(BLEProtocol::AddressType_t *typeP, BLEProtocol::AddressBytes_t address) {
         return gap().getAddress(typeP, address);
@@ -298,9 +259,10 @@
     /**
      * Set the GAP advertising mode to use for this device.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.setAdvertisingType(...) should be replaced with
-     *             ble.gap().setAdvertisingType(...).
+     * @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(...).
      */
     void setAdvertisingType(GapAdvertisingParams::AdvertisingType advType) {
         gap().setAdvertisingType(advType);
@@ -317,15 +279,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.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.setAdvertisingInterval(...) should be replaced with
-     *             ble.gap().setAdvertisingInterval(...).
+     * @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
@@ -338,9 +301,10 @@
     /**
      * @return Minimum Advertising interval in milliseconds.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.getMinAdvertisingInterval(...) should be replaced with
-     *             ble.gap().getMinAdvertisingInterval(...).
+     * @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(...).
      */
     uint16_t getMinAdvertisingInterval(void) const {
         return gap().getMinAdvertisingInterval();
@@ -349,9 +313,10 @@
     /**
      * @return Minimum Advertising interval in milliseconds for non-connectible mode.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.getMinNonConnectableAdvertisingInterval(...) should be replaced with
-     *             ble.gap().getMinNonConnectableAdvertisingInterval(...).
+     * @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(...).
      */
     uint16_t getMinNonConnectableAdvertisingInterval(void) const {
         return gap().getMinNonConnectableAdvertisingInterval();
@@ -360,9 +325,10 @@
     /**
      * @return Maximum Advertising interval in milliseconds.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.getMaxAdvertisingInterval(...) should be replaced with
-     *             ble.gap().getMaxAdvertisingInterval(...).
+     * @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(...).
      */
     uint16_t getMaxAdvertisingInterval(void) const {
         return gap().getMaxAdvertisingInterval();
@@ -373,9 +339,10 @@
      *              Advertising timeout (in seconds) between 0x1 and 0x3FFF (1
      *              and 16383). Use 0 to disable the advertising timeout.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.setAdvertisingTimeout(...) should be replaced with
-     *             ble.gap().setAdvertisingTimeout(...).
+     * @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(...).
      */
     void setAdvertisingTimeout(uint16_t timeout) {
         gap().setAdvertisingTimeout(timeout);
@@ -387,9 +354,10 @@
      * directly; there are other APIs to tweak advertisement parameters
      * individually (see above).
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.setAdvertisingParams(...) should be replaced with
-     *             ble.gap().setAdvertisingParams(...).
+     * @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(...).
      */
     void setAdvertisingParams(const GapAdvertisingParams &advParams) {
         gap().setAdvertisingParams(advParams);
@@ -399,9 +367,10 @@
      * @return  Read back advertising parameters. Useful for storing and
      *          restoring parameters rapidly.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.getAdvertisingParams(...) should be replaced with
-     *             ble.gap().getAdvertisingParams(...).
+     * @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(...).
      */
     const GapAdvertisingParams &getAdvertisingParams(void) const {
         return gap().getAdvertisingParams();
@@ -418,9 +387,10 @@
      *              GapAdvertisingData::Flags for valid flags. Multiple
      *              flags may be specified in combination.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.accumulateAdvertisingPayload(flags) should be replaced with
-     *             ble.gap().accumulateAdvertisingPayload(flags).
+     * @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).
      */
     ble_error_t accumulateAdvertisingPayload(uint8_t flags) {
         return gap().accumulateAdvertisingPayload(flags);
@@ -435,9 +405,10 @@
      * @param[in] app
      *              The appearance of the peripheral.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.accumulateAdvertisingPayload(appearance) should be replaced with
-     *             ble.gap().accumulateAdvertisingPayload(appearance).
+     * @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).
      */
     ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
         return gap().accumulateAdvertisingPayload(app);
@@ -449,13 +420,14 @@
      * as an additional 31 bytes if the advertising payload is too
      * small.
      *
-     * @param[in] power
+     * @param[in] app
      *              The max transmit power to be used by the controller. This
      *              is only a hint.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with
-     *             ble.gap().accumulateAdvertisingPayloadTxPower(txPower).
+     * @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).
      */
     ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
         return gap().accumulateAdvertisingPayloadTxPower(power);
@@ -471,9 +443,10 @@
      * @param  data Data bytes.
      * @param  len  Data length.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.accumulateAdvertisingPayload(...) should be replaced with
-     *             ble.gap().accumulateAdvertisingPayload(...).
+     * @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(...).
      */
     ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
         return gap().accumulateAdvertisingPayload(type, data, len);
@@ -484,9 +457,10 @@
      * underlying stack. It would be uncommon for this API to be used directly;
      * there are other APIs to build an advertisement payload (see above).
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.setAdvertisingData(...) should be replaced with
-     *             ble.gap().setAdvertisingPayload(...).
+     * @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(...).
      */
     ble_error_t setAdvertisingData(const GapAdvertisingData &advData) {
         return gap().setAdvertisingPayload(advData);
@@ -496,9 +470,10 @@
      * @return  Read back advertising data. Useful for storing and
      *          restoring payload.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.getAdvertisingData(...) should be replaced with
-     *             ble.gap().getAdvertisingPayload()(...).
+     * @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()(...).
      */
     const GapAdvertisingData &getAdvertisingData(void) const {
         return gap().getAdvertisingPayload();
@@ -509,25 +484,24 @@
      * accumulateAdvertisingPayload(). This automatically propagates the re-
      * initialized advertising payload to the underlying stack.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.clearAdvertisingPayload(...) should be replaced with
-     *             ble.gap().clearAdvertisingPayload(...).
+     * @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(...).
      */
     void clearAdvertisingPayload(void) {
         gap().clearAdvertisingPayload();
     }
 
     /**
-     * Dynamically reset the accumulated advertising
-     * payload and scanResponse. The application must clear and re-
-     * accumulates a new advertising payload (and scanResponse) before using this
-     * API.
+     * This API is *deprecated* and resolves to a no-operation. It is left here
+     * to allow older code to compile. Please avoid using this API in new code.
+     * This API will be dropped in a future release.
      *
-     * @return BLE_ERROR_NONE when the advertising payload is set successfully.
-     *
-     * @deprecated You should use the parallel API from Gap directly.
-     *
-     * @note The new APIs in Gap update the underlying advertisement payload
+     * Formerly, it would be used to dynamically reset the accumulated advertising
+     * payload and scanResponse; to do this, the application would clear and re-
+     * accumulate a new advertising payload (and scanResponse) before using this
+     * API. Updates to the underlying advertisement payload now happen
      * implicitly.
      */
     ble_error_t setAdvertisingPayload(void) {
@@ -542,9 +516,10 @@
      * @param[in] data Data bytes.
      * @param[in] len  Data length.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.accumulateScanResponse(...) should be replaced with
-     *             ble.gap().accumulateScanResponse(...).
+     * @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(...).
      */
     ble_error_t accumulateScanResponse(GapAdvertisingData::DataType type, const uint8_t *data, uint8_t len) {
         return gap().accumulateScanResponse(type, data, len);
@@ -554,9 +529,10 @@
      * Reset any scan response prepared from prior calls to
      * accumulateScanResponse().
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.clearScanResponse(...) should be replaced with
-     *             ble.gap().clearScanResponse(...).
+     * @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(...).
      */
     void clearScanResponse(void) {
         gap().clearScanResponse();
@@ -565,9 +541,10 @@
     /**
      * Start advertising.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.startAdvertising(...) should be replaced with
-     *             ble.gap().startAdvertising(...).
+     * @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(...).
      */
     ble_error_t startAdvertising(void) {
         return gap().startAdvertising();
@@ -576,9 +553,10 @@
     /**
      * Stop advertising.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.stopAdvertising(...) should be replaced with
-     *             ble.gap().stopAdvertising(...).
+     * @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(...).
      */
     ble_error_t stopAdvertising(void) {
         return gap().stopAdvertising();
@@ -606,11 +584,12 @@
      * 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.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.setScanParams(...) should be replaced with
-     *             ble.gap().setScanParams(...).
+     * @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(...).
      */
     ble_error_t setScanParams(uint16_t interval       = GapScanningParams::SCAN_INTERVAL_MAX,
                               uint16_t window         = GapScanningParams::SCAN_WINDOW_MAX,
@@ -634,9 +613,10 @@
      * Once the scanning parameters have been configured, scanning can be
      * enabled by using startScan().
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.setScanInterval(interval) should be replaced with
-     *             ble.gap().setScanInterval(interval).
+     * @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).
      */
     ble_error_t setScanInterval(uint16_t interval) {
         return gap().setScanInterval(interval);
@@ -657,9 +637,10 @@
      * Once the scanning parameters have been configured, scanning can be
      * enabled by using startScan().
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.setScanWindow(window) should be replaced with
-     *             ble.gap().setScanWindow(window).
+     * @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).
      */
     ble_error_t setScanWindow(uint16_t window) {
         return gap().setScanWindow(window);
@@ -680,11 +661,12 @@
      * 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.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.setScanTimeout(...) should be replaced with
-     *             ble.gap().setScanTimeout(...).
+     * @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(...).
      */
     ble_error_t setScanTimeout(uint16_t timeout) {
         return gap().setScanTimeout(timeout);
@@ -699,9 +681,10 @@
      * Once the scanning parameters have been configured, scanning can be
      * enabled by using startScan().
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.setActiveScan(...) should be replaced with
-     *             ble.gap().setActiveScanning(...).
+     * @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(...).
      */
     void setActiveScan(bool activeScanning) {
         gap().setActiveScanning(activeScanning);
@@ -716,9 +699,10 @@
      *              receiving every advertisement report. This can be passed in
      *              as NULL, in which case scanning may not be enabled at all.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.startScan(callback) should be replaced with
-     *             ble.gap().startScan(callback).
+     * @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).
      */
     ble_error_t startScan(void (*callback)(const Gap::AdvertisementCallbackParams_t *params)) {
         return gap().startScan(callback);
@@ -727,9 +711,10 @@
     /**
      * Same as above, but this takes an (object, method) pair for a callback.
      *
-     * @deprecated 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).
+     * @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).
      */
     template<typename T>
     ble_error_t startScan(T *object, void (T::*memberCallback)(const Gap::AdvertisementCallbackParams_t *params));
@@ -739,9 +724,10 @@
      *
      * @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.stopScan() should be replaced with
-     *             ble.gap().stopScan().
+     * @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().
      */
     ble_error_t stopScan(void) {
         return gap().stopScan();
@@ -761,9 +747,10 @@
      *     successfully. The onConnection callback (if set) is invoked upon
      *     a connection event.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.connect(...) should be replaced with
-     *             ble.gap().connect(...).
+     * @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(...).
      */
     ble_error_t connect(const BLEProtocol::AddressBytes_t  peerAddr,
                         BLEProtocol::AddressType_t         peerAddrType = BLEProtocol::AddressType::RANDOM_STATIC,
@@ -793,27 +780,28 @@
      * @param  reason
      *           The reason for disconnection; sent back to the peer.
      *
-     * @deprecated 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 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.
-     *
-     * @deprecated You should use the parallel API from Gap directly.
+     * connection. This API should be considered *deprecated* in favour of the
+     * alternative, which takes a connection handle. It will be dropped in the future.
      */
     ble_error_t disconnect(Gap::DisconnectionReason_t reason) {
         return gap().disconnect(reason);
     }
 
     /**
-     * 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.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.getGapState() should be replaced with
-     *             ble.gap().getState().
+     * @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().
      */
     Gap::GapState_t getGapState(void) const {
         return gap().getState();
@@ -831,9 +819,10 @@
      * @return BLE_ERROR_NONE if the parameters were successfully filled into
      * the given structure pointed to by params.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.getPreferredConnectionParams() should be replaced with
-     *             ble.gap().getPreferredConnectionParams().
+     * @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().
      */
     ble_error_t getPreferredConnectionParams(Gap::ConnectionParams_t *params) {
         return gap().getPreferredConnectionParams(params);
@@ -847,9 +836,10 @@
      * @param[in] params
      *               The structure containing the desired parameters.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.setPreferredConnectionParams() should be replaced with
-     *             ble.gap().setPreferredConnectionParams().
+     * @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().
      */
     ble_error_t setPreferredConnectionParams(const Gap::ConnectionParams_t *params) {
         return gap().setPreferredConnectionParams(params);
@@ -865,36 +855,38 @@
      *              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.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.updateConnectionParams() should be replaced with
-     *             ble.gap().updateConnectionParams().
+     * @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().
      */
     ble_error_t updateConnectionParams(Gap::Handle_t handle, const Gap::ConnectionParams_t *params) {
         return gap().updateConnectionParams(handle, params);
     }
 
     /**
-     * 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.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.setDeviceName() should be replaced with
-     *             ble.gap().setDeviceName().
+     * @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().
      */
     ble_error_t setDeviceName(const uint8_t *deviceName) {
         return gap().setDeviceName(deviceName);
     }
 
     /**
-     * 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).
@@ -904,35 +896,38 @@
      *     number of bytes actually returned in deviceName. The application may
      *     use this information to retry with a suitable buffer size.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.getDeviceName() should be replaced with
-     *             ble.gap().getDeviceName().
+     * @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().
      */
     ble_error_t getDeviceName(uint8_t *deviceName, unsigned *lengthP) {
         return gap().getDeviceName(deviceName, lengthP);
     }
 
     /**
-     * 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.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.setAppearance() should be replaced with
-     *             ble.gap().setAppearance().
+     * @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().
      */
     ble_error_t setAppearance(GapAdvertisingData::Appearance appearance) {
         return gap().setAppearance(appearance);
     }
 
     /**
-     * Get the appearance characteristic in the Gap service.
-     * @param[out] appearanceP
+     * Get the appearance characteristic in the GAP service.
+     * @param[out] appearance
      *               The new value for the device-appearance.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.getAppearance() should be replaced with
-     *             ble.gap().getAppearance().
+     * @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().
      */
     ble_error_t getAppearance(GapAdvertisingData::Appearance *appearanceP) {
         return gap().getAppearance(appearanceP);
@@ -942,9 +937,10 @@
      * Set the radio's transmit power.
      * @param[in] txPower Radio transmit power in dBm.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.setTxPower() should be replaced with
-     *             ble.gap().setTxPower().
+     * @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().
      */
     ble_error_t setTxPower(int8_t txPower) {
         return gap().setTxPower(txPower);
@@ -958,9 +954,10 @@
      * @param[out] countP
      *                 Out parameter to receive the array's size.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call to
-     *             ble.getPermittedTxPowerValues() should be replaced with
-     *             ble.gap().getPermittedTxPowerValues().
+     * @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().
      */
     void getPermittedTxPowerValues(const int8_t **valueArrayPP, size_t *countP) {
         gap().getPermittedTxPowerValues(valueArrayPP, countP);
@@ -970,9 +967,10 @@
      * Add a service declaration to the local server ATT table. Also add the
      * characteristics contained within.
      *
-     * @deprecated You should use the parallel API from GattServer directly. A former call
-     *             to ble.addService() should be replaced with
-     *             ble.gattServer().addService().
+     * @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().
      */
     ble_error_t addService(GattService &service) {
         return gattServer().addService(service);
@@ -984,7 +982,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
@@ -993,9 +991,10 @@
      *
      * @return BLE_ERROR_NONE if a value was read successfully into the buffer.
      *
-     * @deprecated You should use the parallel API from GattServer directly. A former call
-     *             to ble.readCharacteristicValue() should be replaced with
-     *             ble.gattServer().read().
+     * @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().
      */
     ble_error_t readCharacteristicValue(GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) {
         return gattServer().read(attributeHandle, buffer, lengthP);
@@ -1009,7 +1008,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,9 +1021,10 @@
      *     parameter to allow fetches for connection-specific multivalued
      *     attributes (such as the CCCDs).
      *
-     * @deprecated You should use the parallel API from GattServer directly. A former call
-     *             to ble.readCharacteristicValue() should be replaced with
-     *             ble.gattServer().read().
+     * @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().
      */
     ble_error_t readCharacteristicValue(Gap::Handle_t connectionHandle, GattAttribute::Handle_t attributeHandle, uint8_t *buffer, uint16_t *lengthP) {
         return gattServer().read(connectionHandle, attributeHandle, buffer, lengthP);
@@ -1048,9 +1048,10 @@
      *
      * @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
      *
-     * @deprecated You should use the parallel API from GattServer directly. A former call
-     *             to ble.updateCharacteristicValue() should be replaced with
-     *             ble.gattServer().write().
+     * @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().
      */
     ble_error_t updateCharacteristicValue(GattAttribute::Handle_t  attributeHandle,
                                           const uint8_t           *value,
@@ -1081,9 +1082,10 @@
      *
      * @return BLE_ERROR_NONE if we have successfully set the value of the attribute.
      *
-     * @deprecated You should use the parallel API from GattServer directly. A former call
-     *             to ble.updateCharacteristicValue() should be replaced with
-     *             ble.gattServer().write().
+     * @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().
      */
     ble_error_t updateCharacteristicValue(Gap::Handle_t            connectionHandle,
                                           GattAttribute::Handle_t  attributeHandle,
@@ -1108,9 +1110,10 @@
      *
      * @return BLE_ERROR_NONE on success.
      *
-     * @deprecated You should use the parallel API from SecurityManager directly. A former
-     *             call to ble.initializeSecurity(...) should be replaced with
-     *             ble.securityManager().init(...).
+     * @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(...).
      */
     ble_error_t initializeSecurity(bool                                      enableBonding = true,
                                    bool                                      requireMITM   = true,
@@ -1127,9 +1130,10 @@
      *
      * @return BLE_SUCCESS or appropriate error code indicating the reason of failure.
      *
-     * @deprecated You should use the parallel API from SecurityManager directly. A former
-     *             call to ble.getLinkSecurity(...) should be replaced with
-     *             ble.securityManager().getLinkSecurity(...).
+     * @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(...).
      */
     ble_error_t getLinkSecurity(Gap::Handle_t connectionHandle, SecurityManager::LinkSecurityStatus_t *securityStatusP) {
         return securityManager().getLinkSecurity(connectionHandle, securityStatusP);
@@ -1143,9 +1147,10 @@
      * @retval BLE_ERROR_INVALID_STATE    If the API is called without module initialization or
      *                                    application registration.
      *
-     * @deprecated You should use the parallel API from SecurityManager directly. A former
-     *             call to ble.purgeAllBondingState() should be replaced with
-     *             ble.securityManager().purgeAllBondingState().
+     * @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().
      */
     ble_error_t purgeAllBondingState(void) {
         return securityManager().purgeAllBondingState();
@@ -1155,9 +1160,10 @@
      * Set up a callback for timeout events. Refer to Gap::TimeoutSource_t for
      * possible event types.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call
-     *             to ble.onTimeout(callback) should be replaced with
-     *             ble.gap().onTimeout(callback).
+     * @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).
      */
     void onTimeout(Gap::TimeoutEventCallback_t timeoutCallback) {
         gap().onTimeout(timeoutCallback);
@@ -1166,9 +1172,10 @@
     /**
      * Set up a callback for connection events. Refer to Gap::ConnectionEventCallback_t.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call
-     *             to ble.onConnection(callback) should be replaced with
-     *             ble.gap().onConnection(callback).
+     * @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).
      */
     void onConnection(Gap::ConnectionEventCallback_t connectionCallback) {
         gap().onConnection(connectionCallback);
@@ -1177,22 +1184,15 @@
     /**
      * Append to a chain of callbacks to be invoked upon GAP disconnection.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call
-     *             to ble.onDisconnection(callback) should be replaced with
-     *             ble.gap().onDisconnection(callback).
+     * @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).
      */
     void onDisconnection(Gap::DisconnectionEventCallback_t disconnectionCallback) {
         gap().onDisconnection(disconnectionCallback);
     }
 
-    /**
-     * The same as onDisconnection(), but allows an object reference and member function
-     * to be added to the chain of callbacks.
-     *
-     * @deprecated 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);
@@ -1214,9 +1214,10 @@
      *          The application handler to be invoked in response to a radio
      *          ACTIVE/INACTIVE event.
      *
-     * @deprecated You should use the parallel API from Gap directly. A former call
-     *             to ble.onRadioNotification(...) should be replaced with
-     *             ble.gap().onRadioNotification(...).
+     * @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(...).
      */
     void onRadioNotification(void (*callback)(bool)) {
         gap().onRadioNotification(callback);
@@ -1226,29 +1227,21 @@
      * 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.
      *
-     * @deprecated You should use the parallel API from GattServer directly. A former call
-     *             to ble.onDataSent(...) should be replaced with
-     *             ble.gattServer().onDataSent(...).
+     * @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(...).
      */
     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.
-     *
-     * @deprecated 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);
     }
@@ -1260,30 +1253,22 @@
      * 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.
      *
-     * @deprecated You should use the parallel API from GattServer directly. A former call
-     *             to ble.onDataWritten(...) should be replaced with
-     *             ble.gattServer().onDataWritten(...).
+     * @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(...).
      */
     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.
-     *
-     * @deprecated 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);
     }
@@ -1292,37 +1277,29 @@
      * 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.
      *
-     * @deprecated You should use the parallel API from GattServer directly. A former call
-     *             to ble.onDataRead(...) should be replaced with
-     *             ble.gattServer().onDataRead(...).
+     * @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(...).
      */
     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.
-     *
-     * @deprecated 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);
     }
@@ -1331,9 +1308,10 @@
      * Set up a callback for when notifications or indications are enabled for a
      * characteristic on the local GattServer.
      *
-     * @deprecated You should use the parallel API from GattServer directly. A former call
-     *             to ble.onUpdatesEnabled(callback) should be replaced with
-     *             ble.gattServer().onUpdatesEnabled(callback).
+     * @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).
      */
     void onUpdatesEnabled(GattServer::EventCallback_t callback) {
         gattServer().onUpdatesEnabled(callback);
@@ -1343,9 +1321,10 @@
      * Set up a callback for when notifications or indications are disabled for a
      * characteristic on the local GattServer.
      *
-     * @deprecated You should use the parallel API from GattServer directly. A former call
-     *             to ble.onUpdatesEnabled(callback) should be replaced with
-     *             ble.gattServer().onUpdatesEnabled(callback).
+     * @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).
      */
     void onUpdatesDisabled(GattServer::EventCallback_t callback) {
         gattServer().onUpdatesDisabled(callback);
@@ -1355,9 +1334,10 @@
      * Set up a callback for when the GATT server receives a response for an
      * indication event sent previously.
      *
-     * @deprecated You should use the parallel API from GattServer directly. A former call
-     *             to ble.onConfirmationReceived(callback) should be replaced with
-     *             ble.gattServer().onConfirmationReceived(callback).
+     * @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).
      */
     void onConfirmationReceived(GattServer::EventCallback_t callback) {
         gattServer().onConfirmationReceived(callback);
@@ -1370,9 +1350,10 @@
      * security request: bool allowBonding, bool requireMITM, and
      * SecurityIOCapabilities_t.
      *
-     * @deprecated You should use the parallel API from SecurityManager directly. A former
-     *             call to ble.onSecuritySetupInitiated(callback) should be replaced with
-     *             ble.securityManager().onSecuritySetupInitiated(callback).
+     * @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).
      */
     void onSecuritySetupInitiated(SecurityManager::SecuritySetupInitiatedCallback_t callback) {
         securityManager().onSecuritySetupInitiated(callback);
@@ -1384,9 +1365,10 @@
      * devices. The callback is passed in the success/failure status of the
      * security setup procedure.
      *
-     * @deprecated You should use the parallel API from SecurityManager directly. A former
-     *             call to ble.onSecuritySetupCompleted(callback) should be replaced with
-     *             ble.securityManager().onSecuritySetupCompleted(callback).
+     * @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).
      */
     void onSecuritySetupCompleted(SecurityManager::SecuritySetupCompletedCallback_t callback) {
         securityManager().onSecuritySetupCompleted(callback);
@@ -1400,9 +1382,10 @@
      * or both sides. The callback is passed in a SecurityManager::SecurityMode_t according
      * to the level of security in effect for the secured link.
      *
-     * @deprecated You should use the parallel API from SecurityManager directly. A former
-     *             call to ble.onLinkSecured(callback) should be replaced with
-     *             ble.securityManager().onLinkSecured(callback).
+     * @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).
      */
     void onLinkSecured(SecurityManager::LinkSecuredCallback_t callback) {
         securityManager().onLinkSecured(callback);
@@ -1412,9 +1395,10 @@
      * Set up a callback for successful bonding, meaning that link-specific security
      * context is stored persistently for a peer device.
      *
-     * @deprecated You should use the parallel API from SecurityManager directly. A former
-     *             call to ble.onSecurityContextStored(callback) should be replaced with
-     *             ble.securityManager().onSecurityContextStored(callback).
+     * @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).
      */
     void onSecurityContextStored(SecurityManager::HandleSpecificEvent_t callback) {
         securityManager().onSecurityContextStored(callback);
@@ -1427,9 +1411,10 @@
      * a passkey (or PIN) to authenticate the connection
      * attempt.
      *
-     * @deprecated You should use the parallel API from SecurityManager directly. A former
-     *             call to ble.onPasskeyDisplay(callback) should be replaced with
-     *             ble.securityManager().onPasskeyDisplay(callback).
+     * @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).
      */
     void onPasskeyDisplay(SecurityManager::PasskeyDisplayCallback_t callback) {
         return securityManager().onPasskeyDisplay(callback);
@@ -1453,8 +1438,7 @@
     BLEInstanceBase *transport; /* The device-specific backend */
 };
 
-typedef BLE BLEDevice; /**< @deprecated This type alias is retained for the
-                        * sake of compatibility with older
+typedef BLE BLEDevice; /* DEPRECATED. This type alias is retained for the sake of compatibility with older
                         * code. Will be dropped at some point soon.*/
 
 #endif // ifndef __BLE_H__
\ No newline at end of file