Diff: ble/BLE.h

Revision:

1144:249843612f87

Parent:

1142:a358d0d20f62

Child:

1155:e28c7aac64ab

--- a/ble/BLE.h	Wed Apr 06 19:14:11 2016 +0100
+++ b/ble/BLE.h	Wed Apr 06 19:14:12 2016 +0100
@@ -275,10 +275,9 @@
      * 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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.setAddress(...) should be replaced with
-     * ble.gap().setAddress(...).
+     * @deprecated 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);
@@ -288,10 +287,9 @@
      * 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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.getAddress(...) should be replaced with
-     * ble.gap().getAddress(...).
+     * @deprecated 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);
@@ -300,10 +298,9 @@
     /**
      * Set the GAP advertising mode to use for this device.
      *
-     * @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(...).
+     * @deprecated 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);
@@ -324,10 +321,9 @@
      * 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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.setAdvertisingInterval(...) should be replaced with
-     * ble.gap().setAdvertisingInterval(...).
+     * @deprecated 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
      * 'interval' argument. That required an explicit conversion from
@@ -342,10 +338,9 @@
     /**
      * @return Minimum Advertising interval in milliseconds.
      *
-     * @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(...).
+     * @deprecated 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();
@@ -354,10 +349,9 @@
     /**
      * @return Minimum Advertising interval in milliseconds for non-connectible mode.
      *
-     * @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(...).
+     * @deprecated 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();
@@ -366,10 +360,9 @@
     /**
      * @return Maximum Advertising interval in milliseconds.
      *
-     * @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(...).
+     * @deprecated 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();
@@ -380,10 +373,9 @@
      *              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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.setAdvertisingTimeout(...) should be replaced with
-     * ble.gap().setAdvertisingTimeout(...).
+     * @deprecated 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);
@@ -395,10 +387,9 @@
      * 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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.setAdvertisingParams(...) should be replaced with
-     * ble.gap().setAdvertisingParams(...).
+     * @deprecated 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);
@@ -408,10 +399,9 @@
      * @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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.getAdvertisingParams(...) should be replaced with
-     * ble.gap().getAdvertisingParams(...).
+     * @deprecated 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();
@@ -428,10 +418,9 @@
      *              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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.accumulateAdvertisingPayload(flags) should be replaced with
-     * ble.gap().accumulateAdvertisingPayload(flags).
+     * @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).
      */
     ble_error_t accumulateAdvertisingPayload(uint8_t flags) {
         return gap().accumulateAdvertisingPayload(flags);
@@ -446,10 +435,9 @@
      * @param[in] app
      *              The appearance of the peripheral.
      *
-     * @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).
+     * @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).
      */
     ble_error_t accumulateAdvertisingPayload(GapAdvertisingData::Appearance app) {
         return gap().accumulateAdvertisingPayload(app);
@@ -465,10 +453,9 @@
      *              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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.accumulateAdvertisingPayloadTxPower(txPower) should be replaced with
-     * ble.gap().accumulateAdvertisingPayloadTxPower(txPower).
+     * @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).
      */
     ble_error_t accumulateAdvertisingPayloadTxPower(int8_t power) {
         return gap().accumulateAdvertisingPayloadTxPower(power);
@@ -484,10 +471,9 @@
      * @param  data Data bytes.
      * @param  len  Data length.
      *
-     * @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(...).
+     * @deprecated 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);
@@ -498,10 +484,9 @@
      * 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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.setAdvertisingData(...) should be replaced with
-     * ble.gap().setAdvertisingPayload(...).
+     * @deprecated 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);
@@ -511,10 +496,9 @@
      * @return  Read back advertising data. Useful for storing and
      *          restoring payload.
      *
-     * @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()(...).
+     * @deprecated 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();
@@ -525,24 +509,25 @@
      * 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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.clearAdvertisingPayload(...) should be replaced with
-     * ble.gap().clearAdvertisingPayload(...).
+     * @deprecated 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();
     }
 
     /**
-     * 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.
+     * 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.
      *
-     * 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
+     * @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
      * implicitly.
      */
     ble_error_t setAdvertisingPayload(void) {
@@ -557,10 +542,9 @@
      * @param[in] data Data bytes.
      * @param[in] len  Data length.
      *
-     * @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(...).
+     * @deprecated 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);
@@ -570,10 +554,9 @@
      * Reset any scan response prepared from prior calls to
      * 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.clearScanResponse(...) should be replaced with
-     * ble.gap().clearScanResponse(...).
+     * @deprecated 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();
@@ -582,10 +565,9 @@
     /**
      * Start advertising.
      *
-     * @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(...).
+     * @deprecated 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();
@@ -594,10 +576,9 @@
     /**
      * Stop advertising.
      *
-     * @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(...).
+     * @deprecated 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();
@@ -627,10 +608,9 @@
      *
      * @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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.setScanParams(...) should be replaced with
-     * ble.gap().setScanParams(...).
+     * @deprecated 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,
@@ -654,10 +634,9 @@
      * 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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.setScanInterval(interval) should be replaced with
-     * ble.gap().setScanInterval(interval).
+     * @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).
      */
     ble_error_t setScanInterval(uint16_t interval) {
         return gap().setScanInterval(interval);
@@ -678,10 +657,9 @@
      * 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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.setScanWindow(window) should be replaced with
-     * ble.gap().setScanWindow(window).
+     * @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).
      */
     ble_error_t setScanWindow(uint16_t window) {
         return gap().setScanWindow(window);
@@ -704,10 +682,9 @@
      *
      * @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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.setScanTimeout(...) should be replaced with
-     * ble.gap().setScanTimeout(...).
+     * @deprecated 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);
@@ -722,10 +699,9 @@
      * 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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.setActiveScan(...) should be replaced with
-     * ble.gap().setActiveScanning(...).
+     * @deprecated 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);
@@ -740,10 +716,9 @@
      *              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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.startScan(callback) should be replaced with
-     * ble.gap().startScan(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(callback).
      */
     ble_error_t startScan(void (*callback)(const Gap::AdvertisementCallbackParams_t *params)) {
         return gap().startScan(callback);
@@ -752,10 +727,9 @@
     /**
      * 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.
-     * 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).
+     * @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).
      */
     template<typename T>
     ble_error_t startScan(T *object, void (T::*memberCallback)(const Gap::AdvertisementCallbackParams_t *params));
@@ -765,10 +739,9 @@
      *
      * @retval BLE_ERROR_NONE if successfully stopped scanning procedure.
      *
-     * @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().
+     * @deprecated 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();
@@ -788,10 +761,9 @@
      *     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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.connect(...) should be replaced with
-     * ble.gap().connect(...).
+     * @deprecated 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,
@@ -821,15 +793,15 @@
      * @param  reason
      *           The reason for disconnection; sent back to the peer.
      *
-     * @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).
+     * @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 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.
+     * connection.
+     *
+     * @deprecated You should use the parallel API from Gap directly.
      */
     ble_error_t disconnect(Gap::DisconnectionReason_t reason) {
         return gap().disconnect(reason);
@@ -839,10 +811,9 @@
      * 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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.getGapState() should be replaced with
-     * ble.gap().getState().
+     * @deprecated 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();
@@ -860,10 +831,9 @@
      * @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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.getPreferredConnectionParams() should be replaced with
-     * ble.gap().getPreferredConnectionParams().
+     * @deprecated 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);
@@ -877,10 +847,9 @@
      * @param[in] params
      *               The structure containing the desired parameters.
      *
-     * @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().
+     * @deprecated 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);
@@ -896,10 +865,9 @@
      *              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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.updateConnectionParams() should be replaced with
-     * ble.gap().updateConnectionParams().
+     * @deprecated 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);
@@ -910,10 +878,9 @@
      * @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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.setDeviceName() should be replaced with
-     * ble.gap().setDeviceName().
+     * @deprecated 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);
@@ -937,10 +904,9 @@
      *     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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.getDeviceName() should be replaced with
-     * ble.gap().getDeviceName().
+     * @deprecated 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);
@@ -951,10 +917,9 @@
      * @param[in] appearance
      *              The new value for the device-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.setAppearance() should be replaced with
-     * ble.gap().setAppearance().
+     * @deprecated 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);
@@ -965,10 +930,9 @@
      * @param[out] appearanceP
      *               The new value for the device-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.getAppearance() should be replaced with
-     * ble.gap().getAppearance().
+     * @deprecated 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);
@@ -978,10 +942,9 @@
      * 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.
-     * You should use the parallel API from Gap directly. A former call to
-     * ble.setTxPower() should be replaced with
-     * ble.gap().setTxPower().
+     * @deprecated 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);
@@ -995,10 +958,9 @@
      * @param[out] countP
      *                 Out parameter to receive the array's size.
      *
-     * @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().
+     * @deprecated 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);
@@ -1008,10 +970,9 @@
      * 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.
-     * You should use the parallel API from GattServer directly. A former call
-     * to ble.addService() should be replaced with
-     * ble.gattServer().addService().
+     * @deprecated 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);
@@ -1032,10 +993,9 @@
      *
      * @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.
-     * You should use the parallel API from GattServer directly. A former call
-     * to ble.readCharacteristicValue() should be replaced with
-     * ble.gattServer().read().
+     * @deprecated 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);
@@ -1062,10 +1022,9 @@
      *     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.
-     * You should use the parallel API from GattServer directly. A former call
-     * to ble.readCharacteristicValue() should be replaced with
-     * ble.gattServer().read().
+     * @deprecated 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);
@@ -1089,10 +1048,9 @@
      *
      * @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.
-     * You should use the parallel API from GattServer directly. A former call
-     * to ble.updateCharacteristicValue() should be replaced with
-     * ble.gattServer().write().
+     * @deprecated 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,
@@ -1123,10 +1081,9 @@
      *
      * @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.
-     * You should use the parallel API from GattServer directly. A former call
-     * to ble.updateCharacteristicValue() should be replaced with
-     * ble.gattServer().write().
+     * @deprecated 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,
@@ -1151,10 +1108,9 @@
      *
      * @return BLE_ERROR_NONE on success.
      *
-     * @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(...).
+     * @deprecated 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,
@@ -1171,10 +1127,9 @@
      *
      * @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.
-     * You should use the parallel API from SecurityManager directly. A former
-     * call to ble.getLinkSecurity(...) should be replaced with
-     * ble.securityManager().getLinkSecurity(...).
+     * @deprecated 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);
@@ -1188,10 +1143,9 @@
      * @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.
-     * You should use the parallel API from SecurityManager directly. A former
-     * call to ble.purgeAllBondingState() should be replaced with
-     * ble.securityManager().purgeAllBondingState().
+     * @deprecated 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();
@@ -1201,10 +1155,9 @@
      * 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.
-     * You should use the parallel API from Gap directly. A former call
-     * to ble.onTimeout(callback) should be replaced with
-     * ble.gap().onTimeout(callback).
+     * @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).
      */
     void onTimeout(Gap::TimeoutEventCallback_t timeoutCallback) {
         gap().onTimeout(timeoutCallback);
@@ -1213,10 +1166,9 @@
     /**
      * 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.
-     * You should use the parallel API from Gap directly. A former call
-     * to ble.onConnection(callback) should be replaced with
-     * ble.gap().onConnection(callback).
+     * @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).
      */
     void onConnection(Gap::ConnectionEventCallback_t connectionCallback) {
         gap().onConnection(connectionCallback);
@@ -1225,10 +1177,9 @@
     /**
      * 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.
-     * You should use the parallel API from Gap directly. A former call
-     * to ble.onDisconnection(callback) should be replaced with
-     * ble.gap().onDisconnection(callback).
+     * @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).
      */
     void onDisconnection(Gap::DisconnectionEventCallback_t disconnectionCallback) {
         gap().onDisconnection(disconnectionCallback);
@@ -1238,10 +1189,9 @@
      * 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).
+     * @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*)) {
@@ -1264,10 +1214,9 @@
      *          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.
-     * You should use the parallel API from Gap directly. A former call
-     * to ble.onRadioNotification(...) should be replaced with
-     * ble.gap().onRadioNotification(...).
+     * @deprecated 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);
@@ -1284,10 +1233,9 @@
      * @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.
-     * You should use the parallel API from GattServer directly. A former call
-     * to ble.onDataSent(...) should be replaced with
-     * ble.gattServer().onDataSent(...).
+     * @deprecated 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);
@@ -1297,10 +1245,9 @@
      * 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(...).
+     * @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);
@@ -1321,10 +1268,9 @@
      * @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.
-     * You should use the parallel API from GattServer directly. A former call
-     * to ble.onDataWritten(...) should be replaced with
-     * ble.gattServer().onDataWritten(...).
+     * @deprecated 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);
@@ -1334,10 +1280,9 @@
      * 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(...).
+     * @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);
@@ -1362,10 +1307,9 @@
      * @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.
-     * You should use the parallel API from GattServer directly. A former call
-     * to ble.onDataRead(...) should be replaced with
-     * ble.gattServer().onDataRead(...).
+     * @deprecated 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);
@@ -1375,10 +1319,9 @@
      * 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(...).
+     * @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);
@@ -1388,10 +1331,9 @@
      * 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.
-     * You should use the parallel API from GattServer directly. A former call
-     * to ble.onUpdatesEnabled(callback) should be replaced with
-     * ble.gattServer().onUpdatesEnabled(callback).
+     * @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).
      */
     void onUpdatesEnabled(GattServer::EventCallback_t callback) {
         gattServer().onUpdatesEnabled(callback);
@@ -1401,10 +1343,9 @@
      * 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.
-     * You should use the parallel API from GattServer directly. A former call
-     * to ble.onUpdatesEnabled(callback) should be replaced with
-     * ble.gattServer().onUpdatesEnabled(callback).
+     * @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).
      */
     void onUpdatesDisabled(GattServer::EventCallback_t callback) {
         gattServer().onUpdatesDisabled(callback);
@@ -1414,10 +1355,9 @@
      * 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.
-     * You should use the parallel API from GattServer directly. A former call
-     * to ble.onConfirmationReceived(callback) should be replaced with
-     * ble.gattServer().onConfirmationReceived(callback).
+     * @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).
      */
     void onConfirmationReceived(GattServer::EventCallback_t callback) {
         gattServer().onConfirmationReceived(callback);
@@ -1430,10 +1370,9 @@
      * security request: bool allowBonding, bool requireMITM, and
      * SecurityIOCapabilities_t.
      *
-     * @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).
+     * @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).
      */
     void onSecuritySetupInitiated(SecurityManager::SecuritySetupInitiatedCallback_t callback) {
         securityManager().onSecuritySetupInitiated(callback);
@@ -1445,10 +1384,9 @@
      * 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.
-     * You should use the parallel API from SecurityManager directly. A former
-     * call to ble.onSecuritySetupCompleted(callback) should be replaced with
-     * ble.securityManager().onSecuritySetupCompleted(callback).
+     * @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).
      */
     void onSecuritySetupCompleted(SecurityManager::SecuritySetupCompletedCallback_t callback) {
         securityManager().onSecuritySetupCompleted(callback);
@@ -1462,10 +1400,9 @@
      * 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.
-     * You should use the parallel API from SecurityManager directly. A former
-     * call to ble.onLinkSecured(callback) should be replaced with
-     * ble.securityManager().onLinkSecured(callback).
+     * @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).
      */
     void onLinkSecured(SecurityManager::LinkSecuredCallback_t callback) {
         securityManager().onLinkSecured(callback);
@@ -1475,10 +1412,9 @@
      * 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.
-     * You should use the parallel API from SecurityManager directly. A former
-     * call to ble.onSecurityContextStored(callback) should be replaced with
-     * ble.securityManager().onSecurityContextStored(callback).
+     * @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).
      */
     void onSecurityContextStored(SecurityManager::HandleSpecificEvent_t callback) {
         securityManager().onSecurityContextStored(callback);
@@ -1491,10 +1427,9 @@
      * a passkey (or PIN) to authenticate the connection
      * attempt.
      *
-     * @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).
+     * @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).
      */
     void onPasskeyDisplay(SecurityManager::PasskeyDisplayCallback_t callback) {
         return securityManager().onPasskeyDisplay(callback);
@@ -1518,7 +1453,8 @@
     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