Merge pull request #4992 from akosthekiss/ble-doc-fixes

theotherjimmy · web-flow · commit 9f3801bc25c9 · 2017-09-05T11:17:16.000-05:00
Fix BLE API docs
diff --git a/features/FEATURE_BLE/ble/BLE.h b/features/FEATURE_BLE/ble/BLE.h
@@ -798,7 +798,7 @@ class BLE
      * @param connectionParams
      *         Connection parameters.
      * @param scanParams
-     *          Paramters to use while scanning for the peer.
+     *          Parameters to use while scanning for the peer.
      * @return  BLE_ERROR_NONE if connection establishment procedure is started
      *     successfully. The onConnection callback (if set) is invoked upon
      *     a connection event.
diff --git a/features/FEATURE_BLE/ble/BLEProtocol.h b/features/FEATURE_BLE/ble/BLEProtocol.h
@@ -25,7 +25,7 @@
  * A common namespace for types and constants used everywhere in BLE API.
  */
 namespace BLEProtocol {
-    /**<
+    /**
      * A simple container for the enumeration of address-types for Protocol addresses.
      *
      * Adding a struct to encapsulate the contained enumeration prevents
@@ -37,7 +37,7 @@ namespace BLEProtocol {
      * would allow the use of AliasedType::PUBLIC in code.
      */
     struct AddressType {
-        /**< Address-types for Protocol addresses. */
+        /** Address-types for Protocol addresses. */
         enum Type {
             PUBLIC = 0,
             RANDOM_STATIC,
diff --git a/features/FEATURE_BLE/ble/Gap.h b/features/FEATURE_BLE/ble/Gap.h
@@ -56,7 +56,7 @@ class Gap {
      *
      * @deprecated Use BLEProtocol::AddressType_t instead. The following
      *             constants have been left in their deprecated state to
-     *             transparenly support existing applications which may have
+     *             transparently support existing applications which may have
      *             used Gap::ADDR_TYPE_*.
      */
     enum DeprecatedAddressType_t {
@@ -320,7 +320,7 @@ class Gap {
 
     /**
      * Type for the registered callbacks added to the disconnection event
-     * callchain. Refer to Gap::onDisconnetion().
+     * callchain. Refer to Gap::onDisconnection().
      */
     typedef FunctionPointerWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallback_t;
     /**
@@ -447,7 +447,7 @@ class Gap {
      * @param[in] connectionParams
      *              Connection parameters.
      * @param[in] scanParams
-     *              Paramters to be used while scanning for the peer.
+     *              Parameters to be used while scanning for the peer.
      *
      * @return  BLE_ERROR_NONE if connection establishment procedure is started
      *          successfully. The connectionCallChain (if set) will be invoked upon
@@ -516,7 +516,7 @@ class Gap {
      *
      * @deprecated This version of disconnect() doesn't take a connection handle. It
      *             works reliably only for stacks that are limited to a single
-     *             connection. Use instead Gap::disconnect(Handle_t connectionHandle,
+     *             connection. Use Gap::disconnect(Handle_t connectionHandle,
      *             DisconnectionReason_t reason) instead.
      */
     virtual ble_error_t disconnect(DisconnectionReason_t reason) {
diff --git a/features/FEATURE_BLE/ble/GapAdvertisingParams.h b/features/FEATURE_BLE/ble/GapAdvertisingParams.h
@@ -160,7 +160,7 @@ class GapAdvertisingParams {
     }
 
     /**
-     * Get The advertising timeout.
+     * Get the advertising timeout.
      *
      * @return The advertising timeout (in seconds).
      */
diff --git a/features/FEATURE_BLE/ble/GattCallbackParamTypes.h b/features/FEATURE_BLE/ble/GattCallbackParamTypes.h
@@ -31,7 +31,7 @@ struct GattWriteCallbackParams {
         OP_EXEC_WRITE_REQ_NOW    = 0x06,  /**< Execute write request: immediately execute all prepared writes. */
     };
 
-    Gap::Handle_t            connHandle; /**< The handle of the connection that triggered the event */
+    Gap::Handle_t            connHandle; /**< The handle of the connection that triggered the event. */
     GattAttribute::Handle_t  handle;     /**< Attribute Handle to which the write operation applies. */
     WriteOp_t                writeOp;    /**< Type of write operation. */
     uint16_t                 offset;     /**< Offset for the write operation. */
@@ -46,7 +46,7 @@ struct GattWriteCallbackParams {
 };
 
 struct GattReadCallbackParams {
-    Gap::Handle_t            connHandle; /**< The handle of the connection that triggered the event */
+    Gap::Handle_t            connHandle; /**< The handle of the connection that triggered the event. */
     GattAttribute::Handle_t  handle;     /**< Attribute Handle to which the read operation applies. */
     uint16_t                 offset;     /**< Offset for the read operation. */
     uint16_t                 len;        /**< Length (in bytes) of the data to read. */
@@ -75,7 +75,7 @@ enum GattAuthCallbackReply_t {
 };
 
 struct GattWriteAuthCallbackParams {
-    Gap::Handle_t            connHandle; /**< The handle of the connection that triggered the event */
+    Gap::Handle_t            connHandle; /**< The handle of the connection that triggered the event. */
     GattAttribute::Handle_t  handle;     /**< Attribute Handle to which the write operation applies. */
     uint16_t                 offset;     /**< Offset for the write operation. */
     uint16_t                 len;        /**< Length of the incoming data. */
@@ -88,7 +88,7 @@ struct GattWriteAuthCallbackParams {
 };
 
 struct GattReadAuthCallbackParams {
-    Gap::Handle_t            connHandle; /**< The handle of the connection that triggered the event */
+    Gap::Handle_t            connHandle; /**< The handle of the connection that triggered the event. */
     GattAttribute::Handle_t  handle;     /**< Attribute Handle to which the read operation applies. */
     uint16_t                 offset;     /**< Offset for the read operation. */
     uint16_t                 len;        /**< Optional: new length of the outgoing data. */
@@ -105,7 +105,7 @@ struct GattReadAuthCallbackParams {
  * generated at the remote server.
  */
 struct GattHVXCallbackParams {
-  Gap::Handle_t            connHandle; /**< The handle of the connection that triggered the event */
+  Gap::Handle_t            connHandle; /**< The handle of the connection that triggered the event. */
   GattAttribute::Handle_t  handle;     /**< Attribute Handle to which the HVx operation applies. */
   HVXType_t                type;       /**< Indication or Notification, see HVXType_t. */
   uint16_t                 len;        /**< Attribute data length. */
diff --git a/features/FEATURE_BLE/ble/GattCharacteristic.h b/features/FEATURE_BLE/ble/GattCharacteristic.h
@@ -395,7 +395,7 @@ class GattCharacteristic {
     /**
      * Set up callback that will be triggered before the GATT Client is allowed
      * to read this characteristic. The handler will determine the
-     * authorizaion reply for the read.
+     * authorization reply for the read.
      *
      * @param[in] callback
      *      Event handler being registered.
@@ -457,7 +457,8 @@ class GattCharacteristic {
      *         is granted.
      *
      * @note   To authorize or deny the read the params->authorizationReply field
-     *         should be set to true (authorize) or false (deny).
+     *         should be set to AUTH_CALLBACK_REPLY_SUCCESS (authorize) or any
+     *         of the AUTH_CALLBACK_REPLY_ATTERR_* values (deny).
      *
      * @note   If the read is approved and params->data is unchanged (NULL),
      *         the current characteristic value will be used.
@@ -507,7 +508,7 @@ class GattCharacteristic {
     }
 
     /**
-     * Get the characteristic's propertied. Refer to
+     * Get the characteristic's properties. Refer to
      * GattCharacteristic::Properties_t.
      *
      * @return The characteristic's properties.
@@ -548,7 +549,7 @@ class GattCharacteristic {
     /**
      * Check whether write authorization is enabled i.e. check whether a
      * write authorization callback was previously registered. Refer to
-     * GattCharacteristic::setReadAuthorizationCallback().
+     * GattCharacteristic::setWriteAuthorizationCallback().
      *
      * @return true if write authorization is enabled, false otherwise.
      */
@@ -590,7 +591,7 @@ class GattCharacteristic {
     /**
      * The characteristic's descriptor attributes.
      * This contains only CCCDs that has neither the notify nor the indicate
-     * flag set, as thoses are handled by the underlying BLE stack.
+     * flag set, as those are handled by the underlying BLE stack.
      */
     GattAttribute                   **_descriptors;
     /**
@@ -635,9 +636,9 @@ class ReadOnlyGattCharacteristic : public GattCharacteristic {
      * @param[in] uuid
      *              The characteristic's UUID.
      * @param[in] valuePtr
-     *              Pointer to the characterisitic's initial value.
+     *              Pointer to the characteristic's initial value.
      * @param[in] additionalProperties
-     *              Additional characterisitic properties. By default, the
+     *              Additional characteristic properties. By default, the
      *              properties are set to
      *              Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
      * @param[in] descriptors
@@ -673,9 +674,9 @@ class WriteOnlyGattCharacteristic : public GattCharacteristic {
      * @param[in] uuid
      *              The characteristic's UUID.
      * @param[in] valuePtr
-     *              Pointer to the characterisitic's initial value.
+     *              Pointer to the characteristic's initial value.
      * @param[in] additionalProperties
-     *              Additional characterisitic properties. By default, the
+     *              Additional characteristic properties. By default, the
      *              properties are set to
      *              Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE.
      * @param[in] descriptors
@@ -711,9 +712,9 @@ class ReadWriteGattCharacteristic : public GattCharacteristic {
      * @param[in] uuid
      *              The characteristic's UUID.
      * @param[in] valuePtr
-     *              Pointer to the characterisitic's initial value.
+     *              Pointer to the characteristic's initial value.
      * @param[in] additionalProperties
-     *              Additional characterisitic properties. By default, the
+     *              Additional characteristic properties. By default, the
      *              properties are set to
      *              Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE |
      *              Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
@@ -754,7 +755,7 @@ class WriteOnlyArrayGattCharacteristic : public GattCharacteristic {
      *              Pointer to an array of length NUM_ELEMENTS containing the
      *              characteristic's intitial value.
      * @param[in] additionalProperties
-     *              Additional characterisitic properties. By default, the
+     *              Additional characteristic properties. By default, the
      *              properties are set to
      *              Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE.
      * @param[in] descriptors
@@ -794,7 +795,7 @@ class ReadOnlyArrayGattCharacteristic : public GattCharacteristic {
      *              Pointer to an array of length NUM_ELEMENTS containing the
      *              characteristic's intitial value.
      * @param[in] additionalProperties
-     *              Additional characterisitic properties. By default, the
+     *              Additional characteristic properties. By default, the
      *              properties are set to
      *              Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
      * @param[in] descriptors
@@ -834,7 +835,7 @@ class ReadWriteArrayGattCharacteristic : public GattCharacteristic {
      *              Pointer to an array of length NUM_ELEMENTS containing the
      *              characteristic's intitial value.
      * @param[in] additionalProperties
-     *              Additional characterisitic properties. By default, the
+     *              Additional characteristic properties. By default, the
      *              properties are set to
      *              Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE |
      *              Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
diff --git a/features/FEATURE_BLE/ble/GattService.h b/features/FEATURE_BLE/ble/GattService.h
@@ -109,7 +109,7 @@ class GattService {
      * @param[in] index
      *              The index of the characteristic.
      *
-     * @return A pointer to the characterisitic at index @p index.
+     * @return A pointer to the characteristic at index @p index.
      */
     GattCharacteristic *getCharacteristic(uint8_t index) {
         if (index >= _characteristicCount) {
diff --git a/features/FEATURE_BLE/ble/services/DFUService.h b/features/FEATURE_BLE/ble/services/DFUService.h
@@ -96,7 +96,7 @@ class DFUService {
      * chance to clean up.
      *
      * @param[in] params
-     *     Information about the characterisitc being updated.
+     *     Information about the characteristic being updated.
      */
     virtual void onDataWritten(const GattWriteCallbackParams *params) {
         if (params->handle == controlPoint.getValueHandle()) {
@@ -124,16 +124,16 @@ class DFUService {
 protected:
     BLE          &ble;
 
-    /**< Writing to the control characteristic triggers the handover to DFU 
-      *  bootloader. At present, writing anything will do the trick - this needs
-      *  to be improved. */
+    /** Writing to the control characteristic triggers the handover to DFU
+     *  bootloader. At present, writing anything will do the trick - this needs
+     *  to be improved. */
     WriteOnlyArrayGattCharacteristic<uint8_t, SIZEOF_CONTROL_BYTES> controlPoint;
 
-    /**< The packet characteristic in this service doesn't do anything meaningful;
-      *  it is only a placeholder to mimic the corresponding characteristic in the
-      *  actual DFU service implemented by the bootloader. Without this, some
-      *  FOTA clients might get confused, because service definitions change after
-      *  handing control over to the bootloader. */
+    /** The packet characteristic in this service doesn't do anything meaningful;
+     *  it is only a placeholder to mimic the corresponding characteristic in the
+     *  actual DFU service implemented by the bootloader. Without this, some
+     *  FOTA clients might get confused, because service definitions change after
+     *  handing control over to the bootloader. */
     GattCharacteristic  packet;
 
     uint8_t             controlBytes[SIZEOF_CONTROL_BYTES];
diff --git a/features/FEATURE_BLE/ble/services/HeartRateService.h b/features/FEATURE_BLE/ble/services/HeartRateService.h
@@ -112,7 +112,7 @@ class HeartRateService {
      * controlPoint characteristic.
      *
      * @param[in] params
-     *     Information about the characterisitc being updated.
+     *     Information about the characteristic being updated.
      */
     virtual void onDataWritten(const GattWriteCallbackParams *params) {
         if (params->handle == controlPoint.getValueAttribute().getHandle()) {
diff --git a/features/FEATURE_BLE/ble/services/LinkLossService.h b/features/FEATURE_BLE/ble/services/LinkLossService.h
@@ -78,7 +78,7 @@ class LinkLossService {
      * This callback allows receiving updates to the AlertLevel characteristic.
      *
      * @param[in] params
-     *     Information about the characterisitc being updated.
+     *     Information about the characteristic being updated.
      */
     virtual void onDataWritten(const GattWriteCallbackParams *params) {
         if (params->handle == alertLevelChar.getValueHandle()) {
diff --git a/features/FEATURE_BLE/ble/services/UARTService.h b/features/FEATURE_BLE/ble/services/UARTService.h
@@ -45,7 +45,7 @@ extern const uint8_t  UARTServiceRXCharacteristicUUID[UUID::LENGTH_OF_LONG_UUID]
 */
 class UARTService {
 public:
-    /**< Maximum length of data (in bytes) that the UART service module can transmit to the peer. */
+    /** Maximum length of data (in bytes) that the UART service module can transmit to the peer. */
     static const unsigned BLE_UART_SERVICE_MAX_DATA_LEN = (BLE_GATT_MTU_SIZE_DEFAULT - 3);
 
 public:

Original file line number	Diff line number	Diff line change
`@@ -160,7 +160,7 @@ class GapAdvertisingParams {`
`160`	`160`	`}`
`161`	`161`
`162`	`162`	`/**`
`163`		`- * Get The advertising timeout.`
	`163`	`+ * Get the advertising timeout.`
`164`	`164`	`*`
`165`	`165`	`* @return The advertising timeout (in seconds).`
`166`	`166`	`*/`
Original file line number	Diff line number	Diff line change
`@@ -109,7 +109,7 @@ class GattService {`
`109`	`109`	`* @param[in] index`
`110`	`110`	`* The index of the characteristic.`
`111`	`111`	`*`
`112`		`- * @return A pointer to the characterisitic at index @p index.`
	`112`	`+ * @return A pointer to the characteristic at index @p index.`
`113`	`113`	`*/`
`114`	`114`	`GattCharacteristic *getCharacteristic(uint8_t index) {`
`115`	`115`	`if (index >= _characteristicCount) {`
Original file line number	Diff line number	Diff line change
`@@ -112,7 +112,7 @@ class HeartRateService {`
`112`	`112`	`* controlPoint characteristic.`
`113`	`113`	`*`
`114`	`114`	`* @param[in] params`
`115`		`- * Information about the characterisitc being updated.`
	`115`	`+ * Information about the characteristic being updated.`
`116`	`116`	`*/`
`117`	`117`	`virtual void onDataWritten(const GattWriteCallbackParams *params) {`
`118`	`118`	`if (params->handle == controlPoint.getValueAttribute().getHandle()) {`
Original file line number	Diff line number	Diff line change
`@@ -78,7 +78,7 @@ class LinkLossService {`
`78`	`78`	`* This callback allows receiving updates to the AlertLevel characteristic.`
`79`	`79`	`*`
`80`	`80`	`* @param[in] params`
`81`		`- * Information about the characterisitc being updated.`
	`81`	`+ * Information about the characteristic being updated.`
`82`	`82`	`*/`
`83`	`83`	`virtual void onDataWritten(const GattWriteCallbackParams *params) {`
`84`	`84`	`if (params->handle == alertLevelChar.getValueHandle()) {`