Copy edit DiscoveredCharacteristic.h

Make minor copy edits, mostly for active voice and American English.

Author: Amanda Butler

features/FEATURE_BLE/ble/DiscoveredCharacteristic.h

@@ -36,8 +36,8 @@
 /**
  * Representation of a characteristic discovered.
  *
- * Instances of this class are generated by the GattClient discovery procedure
- * initiated with GattClient::launchServiceDiscovery().
+ * The GattClient discovery procedure initiated with
+ * GattClient::launchServiceDiscovery() generates instances of this class.
  *
  * It exposes the main attributes of the discovered characteristic:
  *   - The UUID of the characteristic, it can be retrieved by a call to the
@@ -51,39 +51,39 @@
  * It important to note that the value of the characteristic - if it is
  * accessible - is not fetched at discovery time.
  *
- * The main operations offered by the class are reading, writing and discovering
+ * The main operations the class offers are reading, writing and discovering
  * the descriptors of the characteristic discovered.
  *
  * Reading a discovered characteristic can be accomplished in two different
- * fashion:
+ * fashions:
  *
  * If the user has a callback registered for the data read operation in the
- * GattClient then a call to the read(uint16_t) function will initiate a read of
+ * GattClient, then a call to the read(uint16_t) function will initiate a read of
  * the characteristic. Results of the operation will be pass on the callback
- * registered by GattClient::onDataRead() which process all the responses to
+ * registered by GattClient::onDataRead(), which processes all the responses to
  * read requests. The read request for a given characteristic can be identified
- * by the connection handle and the attribute handle which are present in
+ * by the connection handle and the attribute handle, which are present in
  * GattReadCallbackParams.
  *
  * Another overload (read(uint16_t, const GattClient::ReadCallback_t&)) of the
- * read function accept a completion callback as a last parameter. That
+ * read function accepts a completion callback as a last parameter. That
  * completion callback will be invoked automatically once the response to the
- * read request for that given characteristic has been received. However
+ * read request for that given characteristic has been received. However,
  * convenience came at the expense of dynamic memory usage for the time of the
  * transaction.
  *
  * Similarly, two versions of the write() API are exposed. One where the user
- * has to register a callback handling write response via the function
- * GattClient::onDataWritten() and another one which accept a completion
+ * has to register a callback handling write response through the function
+ * GattClient::onDataWritten() and another one that accepts a completion
  * callback in input.
  *
- * It is also possible to send a write command which is not acknowledged by the
+ * It is also possible to send a write command, which is not acknowledged by the
  * peer server by using the function writeWoResponse().
  *
- * Finally descriptors of the characteristic can be discovered by invoking the
- * function discoverDescriptors which is a shorthand for calling
+ * Finally, descriptors of the characteristic can be discovered by invoking the
+ * function discoverDescriptors, which is shorthand for calling
  * GattClient::discoverCharacteristicDescriptors. That discovery is necessary to
- * enable or disable characteristic notification or indication which is achieved
+ * enable or disable characteristic notification or indication that is achieved
  * by writing on the Client Characteristic Configuration Descriptor (CCCD).
  */
 class DiscoveredCharacteristic {
@@ -96,47 +96,47 @@ class DiscoveredCharacteristic {
          * Permits broadcasts of the characteristic value using the character
          * the Server Characteristic Configuration Descriptor.
          *
-         * @note If set descriptors of the characteristic shall contain a Server
+         * @note If set, descriptors of the characteristic contain a Server
          * Characteristic Configuration Descriptor.
          */
         uint8_t _broadcast :1;
 
         /**
-         * If set the value of the characteristic can be read.
+         * If set, the value of the characteristic can be read.
          */
         uint8_t _read :1;
 
         /**
-         * If set the characteristic value can be written by a write command
+         * If set, a write command can write the characteristic value
          * (write without response).
          */
         uint8_t _writeWoResp :1;
 
         /**
-         * If set clients can issue requests to write the characteristic.
+         * If set, clients can issue requests to write the characteristic.
          */
         uint8_t _write :1;
 
         /**
-         * If set the server can emit notifications of the Characteristic Value
-         * (without client acknowledgement).
+         * If set, the server can emit notifications of the Characteristic Value
+         * (without client acknowledgment).
          *
-         * @note If set descriptors of the characteristic shall contain a Client
+         * @note If set, descriptors of the characteristic contain a Client
          * Characteristic Configuration Descriptor.
          */
         uint8_t _notify :1;
 
         /**
-         * If set the server can emit indication of the Characteristic Value
+         * If set, the server can emit indication of the Characteristic Value
          * (with client acknowledgement).
          *
-         * @note If set descriptors of the characteristic shall contain a Client
+         * @note If set, descriptors of the characteristic contain a Client
          * Characteristic Configuration Descriptor.
          */
         uint8_t _indicate :1;
 
         /**
-         * If set signed write of the Characteristic Value are supported.
+         * If set, signed write of the Characteristic Value is supported.
          */
         uint8_t _authSignedWrite :1;
 
@@ -171,7 +171,7 @@ class DiscoveredCharacteristic {
         /**
          * Return the value of the write without response property.
          *
-         * @return true if the characteristic accept write without response
+         * @return true if the characteristic accepts write without response
          * commands and false otherwise.
          *
          * @see _writeWoResp
@@ -184,7 +184,7 @@ class DiscoveredCharacteristic {
         /**
          * Return the value of the write property.
          *
-         * @return true if writing the characteristic accept write requests and
+         * @return true if writing the characteristic accepts write requests and
          * false otherwise.
          *
          * @see _write
@@ -201,7 +201,7 @@ class DiscoveredCharacteristic {
          * can be configured to notify the characteristic value to a given
          * client and false otherwise.
          *
-         * @note unlike indication the notification procedure does not require
+         * @note unlike indication, the notification procedure does not require
          * acknowledgement from the client.
          *
          * @see _notify
@@ -219,7 +219,7 @@ class DiscoveredCharacteristic {
          * client and false otherwise.
          *
          * @note unlike notification the indication procedure does require
-         * acknowledgement from the client.
+         * acknowledgment from the client.
          *
          * @see _indicate
          */
@@ -231,7 +231,7 @@ class DiscoveredCharacteristic {
         /**
          * Return the value of the authenticated signed writes property.
          *
-         * @return true if the characteristic accept authenticated signed write
+         * @return true if the characteristic accepts authenticated signed write
          * and false otherwise.
          */
         bool authSignedWrite(void) const
@@ -242,8 +242,8 @@ class DiscoveredCharacteristic {
         /**
          * Equal to operator for DiscoveredCharacteristic::Properties_t.
          *
-         * @param[in] lhs The left hand side of the equality expression
-         * @param[in] rhs The right hand side of the equality expression
+         * @param[in] lhs The left hand side of the equality expression.
+         * @param[in] rhs The right hand side of the equality expression.
          *
          * @return true if operands are equals and false otherwise.
          */
@@ -284,8 +284,8 @@ class DiscoveredCharacteristic {
      * of the characteristic.
      *
      * Read responses will be passed to the callback registered in
-     * GattClient::onDataRead(). Read responses to read requests initiated by
-     * this function call will have their GattReadCallbackParams::connHandle
+     * GattClient::onDataRead(). Read responses to read requests that this function
+     * call initiates will have their GattReadCallbackParams::connHandle
      * field equal to the value returned by getConnectionHandle() and their
      * GattReadCallbackParams::handle field equal to the value returned by
      * getValueHandle().
@@ -310,7 +310,7 @@ class DiscoveredCharacteristic {
      * - where the read operation begin.
      *
      * @param[in] onRead Completion callback which will accept the response of
-     * the read request. The callback is copied, it is not necessary to keep it
+     * the read request. The callback is copied; it is unnecessary to keep it
      * in memory after the call.
      *
      * @return BLE_ERROR_NONE if a read has been initiated.
@@ -320,7 +320,7 @@ class DiscoveredCharacteristic {
      * @return BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's
      * properties.
      *
-     * @note This function is similar to read(uint16_t) const however it uses
+     * @note This function is similar to read(uint16_t) const; however, it uses
      * dynamic memory to store the use completion callback.
      */
     ble_error_t read(
@@ -331,8 +331,8 @@ class DiscoveredCharacteristic {
     /**
      * Perform a write without response procedure.
      *
-     * @note Write without responses are not acknowledged by the server and
-     * therefore won't generate any event on the client side.
+     * @note The server does not acknowledge write without responses.
+     * Therefore, they won't generate any event on the client side.
      *
      * @param[in] length The amount of data being written.
      * @param[in] value The bytes being written.
@@ -355,20 +355,20 @@ class DiscoveredCharacteristic {
      * invoked with the descriptor discovered as parameter. When the process
      * ends, the callback onTermination is invoked.
      *
-     * @param[in] onDescriptorDiscovered Callback invoked when a descriptor is
-     * discovered
+     * @param[in] onDescriptorDiscovered Callback is invoked when a descriptor is
+     * discovered.
      *
-     * @param[in] onTermination Callback invoke when the discovery process ends.
+     * @param[in] onTermination Callback is invoked when the discovery process ends.
      *
      * @return BLE_ERROR_NONE if descriptor discovery is launched successfully;
      * else an appropriate error.
      *
-     * @note This function is a shorthand for
-     * GattClient::discoverCharacteristicDescriptors therefore
+     * @note This function is shorthand for
+     * GattClient::discoverCharacteristicDescriptors; therefore,
      * GattClient::isCharacteristicDescriptorDiscoveryActive can be used to
-     * determine if the descriptor discovery and
+     * determine the descriptor discovery and
      * GattClient::terminateCharacteristicDescriptorDiscovery can be used to
-     * ends the discovery process.
+     * end the discovery process.
      */
     ble_error_t discoverDescriptors(
         const CharacteristicDescriptorDiscovery::DiscoveryCallback_t &onDescriptorDiscovered,
@@ -378,16 +378,16 @@ class DiscoveredCharacteristic {
     /**
      * Initiate a write procedure of the characteristic value.
      *
-     * Unlike write without responses (see writeWoResponse()) an acknowledgement
+     * Unlike write without responses (see writeWoResponse()), an acknowledgment
      * is expected for this procedure. The response of the peer GATT server to
-     * the write request will be passed to callbacks registered in
+     * the write request is passed to callbacks registered in
      * GattClient::onDataWritten().
      *
      * Similarly to read responses, responses to write request of this
      * characteristic can be identified by their connection handle (
-     * GattWriteCallbackParams::connHandle) which will be equal to the value
+     * GattWriteCallbackParams::connHandle), which is equal to the value
      * returned by getConnectionHandle() and their attribute handle (
-     * GattWriteCallbackParams::handle) which will be equal to the value
+     * GattWriteCallbackParams::handle), which is equal to the value
      * returned by getValueHandle().
      *
      * @param[in] length The amount of data being written.
@@ -402,16 +402,16 @@ class DiscoveredCharacteristic {
      * @return BLE_ERROR_OPERATION_NOT_PERMITTED due to the characteristic's
      * properties.
      *
-     * @note Internally the API use the write or long write procedure depending
+     * @note Internally, the API uses the write or long write procedure, depending
      * on the number of bytes to write and the MTU size.
      */
     ble_error_t write(uint16_t length, const uint8_t *value) const;
 
     /**
      * Initiate a write procedure of the characteristic value.
      *
-     * Same as write(uint16_t, const uint8_t *) const but accept a completion
-     * callback which will be invoked when the server response is received.
+     * Same as write(uint16_t, const uint8_t *) const but accepts a completion
+     * callback, which is invoked when the server response is received.
      *
      * @param[in] length The amount of bytes to write.
      * @param[in] value The bytes to write.
@@ -492,13 +492,13 @@ class DiscoveredCharacteristic {
     /**
      * Return the last attribute handle of the characteristic definition.
      *
-     * The attribute layout of a characteristic definition is as follows:
-     *   - Declaration attribute (see #getDeclHandle)
-     *   - Value attribute (see #getValueHandle)
+     * The attribute layout of a characteristic definition is:
+     *   - Declaration attribute (see #getDeclHandle).
+     *   - Value attribute (see #getValueHandle).
      *   - Zero or more characteristic descriptors attribute.
      *
      * The last attribute handle is used internally to discover characteristic
-     * descriptors. The discovery operate on the range [ValueHandle + 1 :
+     * descriptors. The discovery operates on the range [ValueHandle + 1 :
      * LastHandle].
      *
      * @return The last handle of this characteristic definition.
@@ -511,19 +511,19 @@ class DiscoveredCharacteristic {
     }
 
     /**
-     * Get the GattClient which can operate on this characteristic.
+     * Get the GattClient, which can operate on this characteristic.
      *
-     * @return The GattClient which can operate on this characteristic.
+     * @return The GattClient, which can operate on this characteristic.
      */
     GattClient* getGattClient()
     {
         return gattc;
     }
 
     /**
-     * Get the GattClient which can operate on this characteristic.
+     * Get the GattClient, which can operate on this characteristic.
      *
-     * @return The GattClient which can operate on this characteristic.
+     * @return The GattClient, which can operate on this characteristic.
      */
     const GattClient* getGattClient() const
     {
@@ -534,7 +534,7 @@ class DiscoveredCharacteristic {
      * @brief Get the connection handle to the GattServer containing this
      * characteristic.
      *
-     * @return Connection handle to the GattServer which contain this
+     * @return Connection handle to the GattServer, which contains this
      * characteristic.
      */
     Gap::Handle_t getConnectionHandle() const