ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Fix BLE API docs 

Some misguidances, some typos, some stylistics, some doxygen misuses.
pull/4992/head
Akos Kiss 2017-08-30 11:15:39 +02:00
parent 4978a08ae2
commit 90b326a664
11 changed files with 41 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
features/FEATURE_BLE/ble/BLE.h
View File

@ -798,7 +798,7 @@ public:
* @param connectionParams * @param connectionParams
* Connection parameters. * Connection parameters.
* @param scanParams * @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 * @return BLE_ERROR_NONE if connection establishment procedure is started
* successfully. The onConnection callback (if set) is invoked upon * successfully. The onConnection callback (if set) is invoked upon
* a connection event. * a connection event.

4
features/FEATURE_BLE/ble/BLEProtocol.h
View File

@ -25,7 +25,7 @@
* A common namespace for types and constants used everywhere in BLE API. * A common namespace for types and constants used everywhere in BLE API.
*/ */
namespace BLEProtocol { namespace BLEProtocol {
/**< /**
* A simple container for the enumeration of address-types for Protocol addresses. * A simple container for the enumeration of address-types for Protocol addresses.
* *
* Adding a struct to encapsulate the contained enumeration prevents * Adding a struct to encapsulate the contained enumeration prevents
@ -37,7 +37,7 @@ namespace BLEProtocol {
* would allow the use of AliasedType::PUBLIC in code. * would allow the use of AliasedType::PUBLIC in code.
*/ */
struct AddressType { struct AddressType {
/**< Address-types for Protocol addresses. */ /** Address-types for Protocol addresses. */
enum Type { enum Type {
PUBLIC = 0, PUBLIC = 0,
RANDOM_STATIC, RANDOM_STATIC,

8
features/FEATURE_BLE/ble/Gap.h
View File

@ -56,7 +56,7 @@ public:
* *
* @deprecated Use BLEProtocol::AddressType_t instead. The following * @deprecated Use BLEProtocol::AddressType_t instead. The following
* constants have been left in their deprecated state to * 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_*. * used Gap::ADDR_TYPE_*.
*/ */
enum DeprecatedAddressType_t { enum DeprecatedAddressType_t {
@ -320,7 +320,7 @@ public:
/** /**
* Type for the registered callbacks added to the disconnection event * 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; typedef FunctionPointerWithContext<const DisconnectionCallbackParams_t*> DisconnectionEventCallback_t;
/** /**
@ -447,7 +447,7 @@ public:
* @param[in] connectionParams * @param[in] connectionParams
* Connection parameters. * Connection parameters.
* @param[in] scanParams * @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 * @return BLE_ERROR_NONE if connection establishment procedure is started
* successfully. The connectionCallChain (if set) will be invoked upon * successfully. The connectionCallChain (if set) will be invoked upon
@ -516,7 +516,7 @@ public:
* *
* @deprecated This version of disconnect() doesn't take a connection handle. It * @deprecated This version of disconnect() doesn't take a connection handle. It
* works reliably only for stacks that are limited to a single * 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. * DisconnectionReason_t reason) instead.
*/ */
virtual ble_error_t disconnect(DisconnectionReason_t reason) { virtual ble_error_t disconnect(DisconnectionReason_t reason) {

2
features/FEATURE_BLE/ble/GapAdvertisingParams.h
View File

@ -160,7 +160,7 @@ public:
} }
/** /**
* Get The advertising timeout. * Get the advertising timeout.
* *
* @return The advertising timeout (in seconds). * @return The advertising timeout (in seconds).
*/ */

10
features/FEATURE_BLE/ble/GattCallbackParamTypes.h
View File

@ -31,7 +31,7 @@ struct GattWriteCallbackParams {
OP_EXEC_WRITE_REQ_NOW = 0x06, /**< Execute write request: immediately execute all prepared writes. */ 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. */ GattAttribute::Handle_t handle; /**< Attribute Handle to which the write operation applies. */
WriteOp_t writeOp; /**< Type of write operation. */ WriteOp_t writeOp; /**< Type of write operation. */
uint16_t offset; /**< Offset for the write operation. */ uint16_t offset; /**< Offset for the write operation. */
@ -46,7 +46,7 @@ struct GattWriteCallbackParams {
}; };
struct GattReadCallbackParams { 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. */ GattAttribute::Handle_t handle; /**< Attribute Handle to which the read operation applies. */
uint16_t offset; /**< Offset for the read operation. */ uint16_t offset; /**< Offset for the read operation. */
uint16_t len; /**< Length (in bytes) of the data to read. */ uint16_t len; /**< Length (in bytes) of the data to read. */
@ -75,7 +75,7 @@ enum GattAuthCallbackReply_t {
}; };
struct GattWriteAuthCallbackParams { 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. */ GattAttribute::Handle_t handle; /**< Attribute Handle to which the write operation applies. */
uint16_t offset; /**< Offset for the write operation. */ uint16_t offset; /**< Offset for the write operation. */
uint16_t len; /**< Length of the incoming data. */ uint16_t len; /**< Length of the incoming data. */
@ -88,7 +88,7 @@ struct GattWriteAuthCallbackParams {
}; };
struct GattReadAuthCallbackParams { 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. */ GattAttribute::Handle_t handle; /**< Attribute Handle to which the read operation applies. */
uint16_t offset; /**< Offset for the read operation. */ uint16_t offset; /**< Offset for the read operation. */
uint16_t len; /**< Optional: new length of the outgoing data. */ uint16_t len; /**< Optional: new length of the outgoing data. */
@ -105,7 +105,7 @@ struct GattReadAuthCallbackParams {
* generated at the remote server. * generated at the remote server.
*/ */
struct GattHVXCallbackParams { 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. */ GattAttribute::Handle_t handle; /**< Attribute Handle to which the HVx operation applies. */
HVXType_t type; /**< Indication or Notification, see HVXType_t. */ HVXType_t type; /**< Indication or Notification, see HVXType_t. */
uint16_t len; /**< Attribute data length. */ uint16_t len; /**< Attribute data length. */

29
features/FEATURE_BLE/ble/GattCharacteristic.h
View File

@ -395,7 +395,7 @@ public:
/** /**
* Set up callback that will be triggered before the GATT Client is allowed * Set up callback that will be triggered before the GATT Client is allowed
* to read this characteristic. The handler will determine the * to read this characteristic. The handler will determine the
* authorizaion reply for the read. * authorization reply for the read.
* *
* @param[in] callback * @param[in] callback
* Event handler being registered. * Event handler being registered.
@ -457,7 +457,8 @@ public:
* is granted. * is granted.
* *
* @note To authorize or deny the read the params->authorizationReply field * @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), * @note If the read is approved and params->data is unchanged (NULL),
* the current characteristic value will be used. * the current characteristic value will be used.
@ -507,7 +508,7 @@ public:
} }
/** /**
* Get the characteristic's propertied. Refer to * Get the characteristic's properties. Refer to
* GattCharacteristic::Properties_t. * GattCharacteristic::Properties_t.
* *
* @return The characteristic's properties. * @return The characteristic's properties.
@ -548,7 +549,7 @@ public:
/** /**
* Check whether write authorization is enabled i.e. check whether a * Check whether write authorization is enabled i.e. check whether a
* write authorization callback was previously registered. Refer to * write authorization callback was previously registered. Refer to
* GattCharacteristic::setReadAuthorizationCallback(). * GattCharacteristic::setWriteAuthorizationCallback().
* *
* @return true if write authorization is enabled, false otherwise. * @return true if write authorization is enabled, false otherwise.
*/ */
@ -590,7 +591,7 @@ private:
/** /**
* The characteristic's descriptor attributes. * The characteristic's descriptor attributes.
* This contains only CCCDs that has neither the notify nor the indicate * 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; GattAttribute **_descriptors;
/** /**
@ -635,9 +636,9 @@ public:
* @param[in] uuid * @param[in] uuid
* The characteristic's UUID. * The characteristic's UUID.
* @param[in] valuePtr * @param[in] valuePtr
* Pointer to the characterisitic's initial value. * Pointer to the characteristic's initial value.
* @param[in] additionalProperties * @param[in] additionalProperties
* Additional characterisitic properties. By default, the * Additional characteristic properties. By default, the
* properties are set to * properties are set to
* Properties_t::BLE_GATT_CHAR_PROPERTIES_READ. * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
* @param[in] descriptors * @param[in] descriptors
@ -673,9 +674,9 @@ public:
* @param[in] uuid * @param[in] uuid
* The characteristic's UUID. * The characteristic's UUID.
* @param[in] valuePtr * @param[in] valuePtr
* Pointer to the characterisitic's initial value. * Pointer to the characteristic's initial value.
* @param[in] additionalProperties * @param[in] additionalProperties
* Additional characterisitic properties. By default, the * Additional characteristic properties. By default, the
* properties are set to * properties are set to
* Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE. * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE.
* @param[in] descriptors * @param[in] descriptors
@ -711,9 +712,9 @@ public:
* @param[in] uuid * @param[in] uuid
* The characteristic's UUID. * The characteristic's UUID.
* @param[in] valuePtr * @param[in] valuePtr
* Pointer to the characterisitic's initial value. * Pointer to the characteristic's initial value.
* @param[in] additionalProperties * @param[in] additionalProperties
* Additional characterisitic properties. By default, the * Additional characteristic properties. By default, the
* properties are set to * properties are set to
* Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE | * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE |
* Properties_t::BLE_GATT_CHAR_PROPERTIES_READ. * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
@ -754,7 +755,7 @@ public:
* Pointer to an array of length NUM_ELEMENTS containing the * Pointer to an array of length NUM_ELEMENTS containing the
* characteristic's intitial value. * characteristic's intitial value.
* @param[in] additionalProperties * @param[in] additionalProperties
* Additional characterisitic properties. By default, the * Additional characteristic properties. By default, the
* properties are set to * properties are set to
* Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE. * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE.
* @param[in] descriptors * @param[in] descriptors
@ -794,7 +795,7 @@ public:
* Pointer to an array of length NUM_ELEMENTS containing the * Pointer to an array of length NUM_ELEMENTS containing the
* characteristic's intitial value. * characteristic's intitial value.
* @param[in] additionalProperties * @param[in] additionalProperties
* Additional characterisitic properties. By default, the * Additional characteristic properties. By default, the
* properties are set to * properties are set to
* Properties_t::BLE_GATT_CHAR_PROPERTIES_READ. * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.
* @param[in] descriptors * @param[in] descriptors
@ -834,7 +835,7 @@ public:
* Pointer to an array of length NUM_ELEMENTS containing the * Pointer to an array of length NUM_ELEMENTS containing the
* characteristic's intitial value. * characteristic's intitial value.
* @param[in] additionalProperties * @param[in] additionalProperties
* Additional characterisitic properties. By default, the * Additional characteristic properties. By default, the
* properties are set to * properties are set to
* Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE | * Properties_t::BLE_GATT_CHAR_PROPERTIES_WRITE |
* Properties_t::BLE_GATT_CHAR_PROPERTIES_READ. * Properties_t::BLE_GATT_CHAR_PROPERTIES_READ.

2
features/FEATURE_BLE/ble/GattService.h
View File

@ -109,7 +109,7 @@ public:
* @param[in] index * @param[in] index
* The index of the characteristic. * 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) { GattCharacteristic *getCharacteristic(uint8_t index) {
if (index >= _characteristicCount) { if (index >= _characteristicCount) {

18
features/FEATURE_BLE/ble/services/DFUService.h
View File

@ -96,7 +96,7 @@ public:
* chance to clean up. * chance to clean up.
* *
* @param[in] params * @param[in] params
* Information about the characterisitc being updated. * Information about the characteristic being updated.
*/ */
virtual void onDataWritten(const GattWriteCallbackParams *params) { virtual void onDataWritten(const GattWriteCallbackParams *params) {
if (params->handle == controlPoint.getValueHandle()) { if (params->handle == controlPoint.getValueHandle()) {
@ -124,16 +124,16 @@ protected:
protected: protected:
BLE &ble; BLE &ble;
/**< Writing to the control characteristic triggers the handover to DFU /** Writing to the control characteristic triggers the handover to DFU
* bootloader. At present, writing anything will do the trick - this needs * bootloader. At present, writing anything will do the trick - this needs
* to be improved. */ * to be improved. */
WriteOnlyArrayGattCharacteristic<uint8_t, SIZEOF_CONTROL_BYTES> controlPoint; WriteOnlyArrayGattCharacteristic<uint8_t, SIZEOF_CONTROL_BYTES> controlPoint;
/**< The packet characteristic in this service doesn't do anything meaningful; /** The packet characteristic in this service doesn't do anything meaningful;
* it is only a placeholder to mimic the corresponding characteristic in the * it is only a placeholder to mimic the corresponding characteristic in the
* actual DFU service implemented by the bootloader. Without this, some * actual DFU service implemented by the bootloader. Without this, some
* FOTA clients might get confused, because service definitions change after * FOTA clients might get confused, because service definitions change after
* handing control over to the bootloader. */ * handing control over to the bootloader. */
GattCharacteristic packet; GattCharacteristic packet;
uint8_t controlBytes[SIZEOF_CONTROL_BYTES]; uint8_t controlBytes[SIZEOF_CONTROL_BYTES];

2
features/FEATURE_BLE/ble/services/HeartRateService.h
View File

@ -112,7 +112,7 @@ public:
* controlPoint characteristic. * controlPoint characteristic.
* *
* @param[in] params * @param[in] params
* Information about the characterisitc being updated. * Information about the characteristic being updated.
*/ */
virtual void onDataWritten(const GattWriteCallbackParams *params) { virtual void onDataWritten(const GattWriteCallbackParams *params) {
if (params->handle == controlPoint.getValueAttribute().getHandle()) { if (params->handle == controlPoint.getValueAttribute().getHandle()) {

2
features/FEATURE_BLE/ble/services/LinkLossService.h
View File

@ -78,7 +78,7 @@ protected:
* This callback allows receiving updates to the AlertLevel characteristic. * This callback allows receiving updates to the AlertLevel characteristic.
* *
* @param[in] params * @param[in] params
* Information about the characterisitc being updated. * Information about the characteristic being updated.
*/ */
virtual void onDataWritten(const GattWriteCallbackParams *params) { virtual void onDataWritten(const GattWriteCallbackParams *params) {
if (params->handle == alertLevelChar.getValueHandle()) { if (params->handle == alertLevelChar.getValueHandle()) {

2
features/FEATURE_BLE/ble/services/UARTService.h
View File

@ -45,7 +45,7 @@ extern const uint8_t UARTServiceRXCharacteristicUUID[UUID::LENGTH_OF_LONG_UUID]
*/ */
class UARTService { class UARTService {
public: 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); static const unsigned BLE_UART_SERVICE_MAX_DATA_LEN = (BLE_GATT_MTU_SIZE_DEFAULT - 3);
public: public: