BLE: Fix doxygen warnings.

Replace @important tag by @attention.
pull/5701/head
Vincent Coubard 2017-12-13 16:14:16 +00:00
parent b4dc32521a
commit 82f669b61f
25 changed files with 79 additions and 80 deletions

View File

@ -280,7 +280,7 @@ public:
* function-pointer, init() can also take an <Object, member> pair as its
* callback target.
*
* @important This should be called before using anything else in the BLE
* @attention This should be called before using anything else in the BLE
* API.
*/
ble_error_t init(InitializationCompleteCallback_t completion_cb = NULL) {
@ -321,7 +321,7 @@ public:
* @return BLE_ERROR_NONE if the instance was shut down without error or the
* appropriate error code.
*
* @important init() must be called afterward to reinstate services and
* @attention init() must be called afterward to reinstate services and
* GAP state. This API offers a way to repopulate the GATT database with new
* services and characteristics.
*/

View File

@ -46,7 +46,7 @@ class GattClient;
* createBLEInstance(). The BLE API uses this singleton function to gain
* access to a concrete implementation of this class defined in the vendor port.
*
* @important This class is part of the porting API and is not meant to be used
* @attention This class is part of the porting API and is not meant to be used
* by end users of BLE API.
*
* @see BLE
@ -237,7 +237,7 @@ public:
* Process pending events present in the vendor subsystem; then, put the MCU
* to sleep until an external source wakes it up.
*
* @important This function is deprecated in the BLE class. It will be
* @attention This function is deprecated in the BLE class. It will be
* removed from this interface once it is removed from BLE.
*
* @see BLE::waitForEvent() BLE::processEvents()
@ -254,10 +254,10 @@ private:
/**
* Return the instance of the vendor implementation of BLEInstanceBase.
*
* @important Contrary to its name, this function does not return a new instance
* @attention Contrary to its name, this function does not return a new instance
* at each call. It rather acts like an accessor to a singleton.
*
* @important The vendor library must provide an implementation for this function
* @attention The vendor library must provide an implementation for this function
* library. Otherwise, there will be a linker error.
*/
extern BLEInstanceBase *createBLEInstance(void);

View File

@ -84,7 +84,7 @@ public:
/**
* Construct a DiscoveredService instance.
*
* @important This API is not meant to be used publicly. It is meant to be
* @attention This API is not meant to be used publicly. It is meant to be
* used by internal APIs of Mbed BLE.
*/
DiscoveredService() :
@ -96,7 +96,7 @@ public:
/**
* Set information about the discovered service.
*
* @important This API is not meant to be used publicly. It is meant to be
* @attention This API is not meant to be used publicly. It is meant to be
* used by internal APIs of Mbed BLE.
*
* @param[in] uuidIn The UUID of the discovered service.
@ -118,7 +118,7 @@ public:
/**
* Set the start and end handle of the discovered service.
*
* @important This API is not meant to be used publicly. It is meant to be
* @attention This API is not meant to be used publicly. It is meant to be
* used by internal APIs of Mbed BLE.
*
* @param[in] startHandleIn The start handle of the discovered service in
@ -137,7 +137,7 @@ public:
/**
* Set the long UUID of the discovered service.
*
* @important This API is not meant to be used publicly. It is meant to be
* @attention This API is not meant to be used publicly. It is meant to be
* used by internal APIs of Mbed BLE.
*
* @param[in] longUUID The bytes composing the long UUID of this discovered

View File

@ -46,7 +46,7 @@
* This class also offers a mechanism to chain other instances to it. When an
* instance is called, all the instances being part of the chain are called.
*
* @important freestanding or member function adapted must accept a single
* @attention freestanding or member function adapted must accept a single
* argument, and this argument is a pointer to ContextType. Adapted
* primitives do not return anything.
*

View File

@ -347,7 +347,7 @@ public:
/**
* Enumeration of disconnection reasons.
*
* @important There might be a mismatch between the disconnection reason
* @attention There might be a mismatch between the disconnection reason
* passed to disconnect() and the disconnection event generated locally
* because the disconnection reason passed to disconnect() is the
* disconnection reason to be transmitted to the peer.
@ -356,7 +356,7 @@ public:
/**
* The connection timed out.
*
* @important shall not be used as a reason in disconnect().
* @attention shall not be used as a reason in disconnect().
*/
CONNECTION_TIMEOUT = 0x08,
@ -379,7 +379,7 @@ public:
* Indicate that the local user or the internal
* Bluetooth subsystem terminated the connection.
*
* @important shall not be used as a reason in disconnect().
* @attention shall not be used as a reason in disconnect().
*/
LOCAL_HOST_TERMINATED_CONNECTION = 0x16,
@ -548,7 +548,7 @@ public:
*
* @note The BLE API does not express the broadcaster and scanner roles.
*
* @important A device can fulfill different roles concurrently.
* @attention A device can fulfill different roles concurrently.
*/
enum Role_t {
/**
@ -2271,7 +2271,7 @@ public:
/**
* Notify all registered connection event handlers of a connection event.
*
* @important This function is meant to be called from the BLE stack specific
* @attention This function is meant to be called from the BLE stack specific
* implementation when a connection event occurs.
*
* @param[in] handle Handle of the new connection.
@ -2312,7 +2312,7 @@ public:
/**
* Notify all registered disconnection event handlers of a disconnection event.
*
* @important This function is meant to be called from the BLE stack specific
* @attention This function is meant to be called from the BLE stack specific
* implementation when a disconnection event occurs.
*
* @param[in] handle Handle of the terminated connection.
@ -2334,7 +2334,7 @@ public:
* Forward a received advertising packet to all registered event handlers
* listening for scanned packet events.
*
* @important This function is meant to be called from the BLE stack specific
* @attention This function is meant to be called from the BLE stack specific
* implementation when a disconnection event occurs.
*
* @param[in] peerAddr Address of the peer that has emitted the packet.
@ -2367,7 +2367,7 @@ public:
* Notify the occurrence of a timeout event to all registered timeout events
* handler.
*
* @important This function is meant to be called from the BLE stack specific
* @attention This function is meant to be called from the BLE stack specific
* implementation when a disconnection event occurs.
*
* @param[in] source Source of the timout event.

View File

@ -166,7 +166,7 @@ public:
/**
* Get a pointer to the current length of the attribute value.
*
* @important note Do not use this function.
* @attention note Do not use this function.
*
* @return A pointer to the current length of the attribute value.
*/
@ -178,7 +178,7 @@ public:
/**
* Set the attribute handle.
*
* @important The GattServer uses this function internally.
* @attention The GattServer uses this function internally.
* Application code must not use it.
*
* @param[in] id The new attribute handle.

View File

@ -31,11 +31,11 @@
* whether the GattServer has received a write request or a GattClient has
* received a write response.
*
* @important The GattServer only populates the fields offset, len and data
* @attention The GattServer only populates the fields offset, len and data
* when it has received a write request. Callbacks attached to the GattClient
* do not use those fields.
*
* @important The GattClient only populates the fields status and error_code
* @attention The GattClient only populates the fields status and error_code
* when it has received a write response. Callbacks attached to the GattServer
* do not use those fields.
*/
@ -99,14 +99,14 @@ struct GattWriteCallbackParams {
/**
* Offset within the attribute value to be written.
*
* @important Reserved for GattServer registered callbacks.
* @attention Reserved for GattServer registered callbacks.
*/
uint16_t offset;
/**
* Status of the GattClient Write operation.
*
* @important Reserved for GattClient registered callbacks.
* @attention Reserved for GattClient registered callbacks.
*/
ble_error_t status;
};
@ -115,14 +115,14 @@ struct GattWriteCallbackParams {
/**
* Length (in bytes) of the data to write.
*
* @important Reserved for GattServer registered callbacks.
* @attention Reserved for GattServer registered callbacks.
*/
uint16_t len;
/**
* Error code of the GattClient Write operation.
*
* @important Reserved for GattClient registered callbacks.
* @attention Reserved for GattClient registered callbacks.
*/
uint8_t error_code;
};
@ -130,9 +130,9 @@ struct GattWriteCallbackParams {
/**
* Pointer to the data to write.
*
* @important Data may not persist beyond the callback scope.
* @attention Data may not persist beyond the callback scope.
*
* @important Reserved for GattServer registered callbacks.
* @attention Reserved for GattServer registered callbacks.
*/
const uint8_t *data;
};
@ -144,7 +144,7 @@ struct GattWriteCallbackParams {
* whether the GattServer has received a read request or a GattClient has
* received a read response.
*
* @important The GattClient only populates the fields status and error_code
* @attention The GattClient only populates the fields status and error_code
* when it has received a read response. Callbacks attached to the GattServer
* do not use those fields.
*/
@ -173,9 +173,9 @@ struct GattReadCallbackParams {
/**
* Error code of the GattClient read operation.
*
* @important Reserved for GattClient registered callbacks.
* @attention Reserved for GattClient registered callbacks.
*
* @important set if status is not equal to BLE_ERROR_NONE; otherwise,
* @attention set if status is not equal to BLE_ERROR_NONE; otherwise,
* this field is interpreted as len.
*/
uint8_t error_code;
@ -184,14 +184,14 @@ struct GattReadCallbackParams {
/**
* Pointer to the data read.
*
* @important Data may not persist beyond the callback scope.
* @attention Data may not persist beyond the callback scope.
*/
const uint8_t *data;
/**
* Status of the GattClient Read operation.
*
* @important Reserved for GattClient registered callbacks.
* @attention Reserved for GattClient registered callbacks.
*/
ble_error_t status;
};

View File

@ -1357,7 +1357,7 @@ public:
* be allocated if either the notify or indicate flag in the @p props bit
* field; the underlying BLE stack handles it.
*
* @important GattCharacteristic registered in a GattServer must remain
* @attention GattCharacteristic registered in a GattServer must remain
* valid for the lifetime of the GattServer.
*/
GattCharacteristic(
@ -1476,7 +1476,7 @@ public:
* This function is a helper that calls the registered write handler to
* determine the authorization reply for a write request.
*
* @important This function is not meant to be called by user code.
* @attention This function is not meant to be called by user code.
*
* @param[in] params Context of the write-auth request; it contains an
* out-parameter used as a reply.
@ -1502,7 +1502,7 @@ public:
* This function is a helper that calls the registered read handler to
* determine the authorization reply for a read request.
*
* @important This function is not meant to be called by user code.
* @attention This function is not meant to be called by user code.
*
* @param[in] params Context of the read-auth request; it contains an
* out-parameter used as a reply and the handler can fill it with outgoing

View File

@ -743,7 +743,7 @@ public:
/**
* Forward an attribute read event to all registered handlers.
*
* @important This function is meant to be called from the vendor
* @attention This function is meant to be called from the vendor
* implementation when an attribute read event occurs.
*
* @param[in] params Attribute read event to pass to the registered handlers.
@ -756,7 +756,7 @@ public:
/**
* Forward an attribute written event to all registered handlers.
*
* @important This function is meant to be called from the vendor
* @attention This function is meant to be called from the vendor
* implementation when an attribute written event occurs.
*
* @param[in] params Attribute written event to pass to the registered
@ -771,7 +771,7 @@ public:
* Forward a handle value notification or indication event to all registered
* handlers.
*
* @important This function is meant to be called from the vendor
* @attention This function is meant to be called from the vendor
* implementation when a notification or indication event is available.
*
* @param[in] params Notification or Indication event to pass to the

View File

@ -195,7 +195,7 @@ public:
* Application code can remove all the registered services by calling
* reset().
*
* @important Service, characteristics and descriptors objects registered
* @attention Service, characteristics and descriptors objects registered
* within the GattServer must remain reachable until reset() is called.
*
* @param[in] service The service to be added; attribute handle of services,
@ -227,7 +227,7 @@ public:
*
* @return BLE_ERROR_NONE if a value was read successfully into the buffer.
*
* @important read(Gap::Handle_t, GattAttribute::Handle_t, uint8_t *, uint16_t *)
* @attention read(Gap::Handle_t, GattAttribute::Handle_t, uint8_t *, uint16_t *)
* must be used to read Client Characteristic Configuration Descriptor (CCCD)
* because the value of this type of attribute depends on the connection.
*/
@ -409,7 +409,7 @@ public:
* Indicate if the underlying stack emit events when an attribute is read by
* a client.
*
* @important This function should be overridden to return true if
* @attention This function should be overridden to return true if
* applicable.
*
* @return true if onDataRead is supported; false otherwise.
@ -465,12 +465,12 @@ public:
}
/**
* Set an event handler that is called after
* Set an event handler that is called after
* a connected peer has written an attribute.
*
* @param[in] callback The event handler being registered.
*
* @important It is possible to set multiple event handlers. Registered
* @attention It is possible to set multiple event handlers. Registered
* handlers may be removed with onDataWritten().detach(callback).
*/
void onDataWritten(const DataWrittenCallback_t &callback)
@ -526,7 +526,7 @@ public:
* @see GattCharacteristic::setReadAuthorizationCallback()
* @see isOnDataReadAvailable().
*
* @important It is possible to set multiple event handlers. Registered
* @attention It is possible to set multiple event handlers. Registered
* handlers may be removed with onDataRead().detach(callback).
*/
ble_error_t onDataRead(const DataReadCallback_t &callback)
@ -668,7 +668,7 @@ protected:
* Helper function that notifies all registered handlers of an occurrence
* of a data written event.
*
* @important Vendor implementation must invoke this function after one of
* @attention Vendor implementation must invoke this function after one of
* the GattServer attributes has been written.
*
* @param[in] params The data written parameters passed to the registered
@ -683,7 +683,7 @@ protected:
* Helper function that notifies all registered handlers of an occurrence
* of a data read event.
*
* @important Vendor implementation must invoke this function after one of
* @attention Vendor implementation must invoke this function after one of
* the GattServer attributes has been read.
*
* @param[in] params The data read parameters passed to the registered
@ -698,7 +698,7 @@ protected:
* Helper function that notifies the registered handler of an occurrence
* of updates enabled, updates disabled or confirmation received events.
*
* @important Vendor implementation must invoke this function when a client
* @attention Vendor implementation must invoke this function when a client
* subscribes to characteristic updates, unsubscribes from characteristic
* updates or a notification confirmation has been received.
*
@ -735,7 +735,7 @@ protected:
* Helper function that notifies all registered handlers of an occurrence
* of a data sent event.
*
* @important Vendor implementation must invoke this function after the
* @attention Vendor implementation must invoke this function after the
* emission of a notification or an indication.
*
* @param[in] count Number of packets sent.

View File

@ -29,7 +29,7 @@
/**
* Abstract events generated by a GattServer vendor port.
*
* @important This class is not part of the public API.
* @attention This class is not part of the public API.
*/
class GattServerEvents
{

View File

@ -143,7 +143,7 @@ public:
* belongs to the service.
* @param[in] numCharacteristics The number of characteristics.
*
* @important The characteristics of the service must remain valid while the
* @attention The characteristics of the service must remain valid while the
* GattServer uses the service.
*/
GattService(
@ -190,7 +190,7 @@ public:
/**
* Set the handle of the service declaration attribute in the ATT table.
*
* @important Application code must not use this API.
* @attention Application code must not use this API.
*
* @param[in] handle The service's handle.
*/

View File

@ -124,7 +124,7 @@ public:
/**
* Avoid conversion to bool between different classes.
*
* @important Will generate a compile time error if instantiated.
* @attention Will generate a compile time error if instantiated.
*/
template <typename T, typename U>
void operator==(const SafeBool<T>& lhs,const SafeBool<U>& rhs)
@ -136,7 +136,7 @@ void operator==(const SafeBool<T>& lhs,const SafeBool<U>& rhs)
/**
* Avoid conversion to bool between different classes.
*
* @important Will generate a compile time error if instantiated.
* @attention Will generate a compile time error if instantiated.
*/
template <typename T,typename U>
void operator!=(const SafeBool<T>& lhs,const SafeBool<U>& rhs)

View File

@ -39,7 +39,7 @@ class DiscoveredCharacteristic;
* This class is also an interface that may be used in vendor port to model
* the service discovery process. This interface is not used in user code.
*
* @important Implementing this interface is not a requirement for the
* @attention Implementing this interface is not a requirement for the
* implementation of the service discover process.
*/
class ServiceDiscovery {
@ -49,7 +49,7 @@ public:
*
* The callback accepts a pointer to a DiscoveredService as parameter.
*
* @important The argument passed to the callback may not persist after the
* @attention The argument passed to the callback may not persist after the
* callback invocation; therefore, the callbacks must make a shallow copy
* of the DiscoveredService passed as parameter to access its value beyond
* the callback scope.
@ -63,7 +63,7 @@ public:
* The callback accepts a pointer to a DiscoveredCharacteristic as
* parameter.
*
* @important The argument passed to the callback may not persist after the
* @attention The argument passed to the callback may not persist after the
* callback invocation; therefore, the callbacks must make a shallow copy
* of the DiscoveredCharacteristic passed as parameter to access its value
* beyond the callback scope.

View File

@ -205,7 +205,7 @@ public:
* shortened version of the UUID 0000xxxx-0000-1000-8000-00805F9B34FB, where
* xxxx is the value of the 16-bit UUID.
*
* @important 16-bit UUIDs are not used in user defined data type or
* @attention 16-bit UUIDs are not used in user defined data type or
* user defined element ID.
*
* @param[in] _shortUUID 16-bit part of the standard UUID.
@ -296,7 +296,7 @@ public:
/**
* Get the uint16_t value of the UUID.
*
* @important This function is not used on long UUIDs.
* @attention This function is not used on long UUIDs.
*
* @return The value of the shortened UUID.
*/

View File

@ -38,7 +38,7 @@ namespace generic {
* It requires a pal::Gap and a pal::GenericAccessService injected at
* construction site.
*
* @important: Not part of the public interface of BLE API.
* @attention: Not part of the public interface of BLE API.
*/
class GenericGap : public ::Gap {

View File

@ -36,7 +36,7 @@ struct descriptor_discovery_control_block_t;
/**
* Generic implementation of the GattClient.
* It requires a pal::GattClient injected at construction site.
* @important: Not part of the public interface of BLE API.
* @attention: Not part of the public interface of BLE API.
*/
class GenericGattClient : public GattClient {

View File

@ -55,7 +55,7 @@ struct EventQueue {
*
* @return true in case of success and false otherwise
*
* @important Event availability shall be signaled to the upper layer and
* @attention Event availability shall be signaled to the upper layer and
* the event queue shall be processed at the next invocation of
* BLEInstanceBase::process
*/

View File

@ -175,13 +175,13 @@ struct GapConnectionCompleteEvent : public GapEvent {
/**
* Handle of the connection created, valid if status is equal to 0.
* @important Valid if status is equal to 0.
* @attention Valid if status is equal to 0.
*/
const connection_handle_t connection_handle;
/**
* Role of the device in the connection
* @important Valid if status is equal to 0.
* @attention Valid if status is equal to 0.
*/
const connection_role_t role;
@ -217,7 +217,7 @@ struct GapConnectionCompleteEvent : public GapEvent {
/**
* Report advertising from one or more LE device.
*
* @important This class has to be implemented by the BLE port.
* @attention This class has to be implemented by the BLE port.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.7.65.2 LE Advertising Report Event
*/
@ -432,7 +432,7 @@ struct GapDisconnectionCompleteEvent : public GapEvent {
/**
* Reason for disconnection.
*
* @important ignored in case of faillure.
* @attention ignored in case of faillure.
*/
const uint8_t reason;
};

View File

@ -293,7 +293,7 @@ struct Gap {
* @parameter filter_duplicates Enable duplicate filtering if true,
* otherwise disable it.
*
* @important advertising data or scan response data is not considered
* @attention advertising data or scan response data is not considered
* significant when determining duplicate advertising reports.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
@ -420,7 +420,7 @@ struct Gap {
/**
* Clear the whitelist stored in the LE subsystem.
*
* @important This command shall not be issued if the whitelist is being
* @attention This command shall not be issued if the whitelist is being
* used by the advertising, scanning or connection creation procedure.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the
@ -441,7 +441,7 @@ struct Gap {
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @important This command shall not be issued if the whitelist is being
* @attention This command shall not be issued if the whitelist is being
* used by the advertising, scanning or connection creation procedure.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.16 LE add device to white list
@ -463,7 +463,7 @@ struct Gap {
* @return BLE_ERROR_NONE if the request has been successfully sent or the
* appropriate error otherwise.
*
* @important This command shall not be issued if the whitelist is being
* @attention This command shall not be issued if the whitelist is being
* used by the advertising, scanning or connection creation procedure.
*
* @note: See Bluetooth 5 Vol 2 PartE: 7.8.17 LE remove device from white
@ -589,7 +589,7 @@ struct Gap {
* @note Usually parameters of this function match the connection parameters
* received in the connection parameter request event.
*
* @important: Once the new connection parameters are in used a Connection
* @attention: Once the new connection parameters are in used a Connection
* Update Complete event shall be emmited.
*
* @return BLE_ERROR_NONE if the request has been successfully sent or the

View File

@ -35,7 +35,7 @@ struct SimpleEventQueue : EventQueue {
/**
* Construct an empty event queue.
*
* @important a call to initialize is mandatory before any other call.
* @attention a call to initialize is mandatory before any other call.
*
* @param ble_instance_id The id of the ble instance associated with that
* event queue.

View File

@ -49,7 +49,7 @@
* @note You can find specification of the battery service here:
* https://www.bluetooth.com/specifications/gatt
*
* @important Multiple instances of this battery service are not supported.
* @attention Multiple instances of this battery service are not supported.
*/
class BatteryService {
public:
@ -95,7 +95,7 @@ public:
* @param newLevel Charge level of the battery. It is a percentage of the
* remaining charge between 0% and 100%.
*
* @important This function must be called in the execution context of the
* @attention This function must be called in the execution context of the
* BLE stack.
*/
void updateBatteryLevel(uint8_t newLevel)

View File

@ -29,7 +29,6 @@
class HealthThermometerService {
public:
/**
* @enum Sensor Location.
* @brief Location of sensor on the body.
*/
enum SensorLocation_t {

View File

@ -49,10 +49,10 @@
* @note You can find specification of the heart rate service here:
* https://www.bluetooth.com/specifications/gatt
*
* @important The service does not expose information related to the sensor
* @attention The service does not expose information related to the sensor
* contact, the accumulated energy expanded or the interbeat intervals.
*
* @important The heart rate profile limits the number of instantiations of the
* @attention The heart rate profile limits the number of instantiations of the
* heart rate services to one.
*/
class HeartRateService {
@ -139,7 +139,7 @@ public:
*
* @param[in] hrmCounter Heart rate measured in BPM.
*
* @important This function must be called in the execution context of the
* @attention This function must be called in the execution context of the
* BLE stack.
*/
void updateHeartRate(uint16_t hrmCounter) {

View File

@ -76,7 +76,7 @@
*
* Beacon configuration and advertising commencement is left to the user.
*
* @important If you are interested in manufacturing iBeacons, you must obtain a
* @attention If you are interested in manufacturing iBeacons, you must obtain a
* license from Apple. More information at https://developer.apple.com/ibeacon/.
* The licence also grant access to the iBeacons technical specification.
*