Merge branch 'iriark01-patch-3' into develop

ble/services/DFUService.h

@@ -37,20 +37,20 @@ extern const uint8_t  DFUServicePacketCharacteristicUUID[];
 class DFUService {
 public:
     /**
-     * @brief Signature for the handover callback. The application may provide such a
-     * callback when setting up the DFU service, in which case it will be
+     * @brief Signature for the handover callback. The application may provide this
+     * callback when setting up the DFU service. The callback is then
      * invoked before handing control over to the bootloader.
      */
     typedef void (*ResetPrepare_t)(void);
 
 public:
     /**
-    * @brief Adds Device Firmware Update service to an existing ble object.
+    * @brief Adds Device Firmware Update Service to an existing BLE object.
     *
     * @param[ref] _ble
     *               BLE object for the underlying controller.
     * @param[in] _handoverCallback
-    *                Application specific handover callback.
+    *                Application-specific handover callback.
     */
     DFUService(BLE &_ble, ResetPrepare_t _handoverCallback = NULL) :
         ble(_ble),
@@ -59,12 +59,12 @@ public:
                GattCharacteristic::BLE_GATT_CHAR_PROPERTIES_WRITE_WITHOUT_RESPONSE),
         controlBytes(),
         packetBytes() {
-        static bool serviceAdded = false; /* We should only ever need to add the DFU service once. */
+        static bool serviceAdded = false; /* We only add the DFU service once. */
         if (serviceAdded) {
             return;
         }
 
-        /* Set an initial value for control bytes so that the application's DFUService can
+        /* Set an initial value for control bytes, so that the application's DFU service can
          * be distinguished from the real DFU service provided by the bootloader. */
         controlBytes[0] = 0xFF;
         controlBytes[1] = 0xFF;
@@ -80,7 +80,7 @@ public:
     }
 
     /**
-    * @brief get the handle for the value attribute of the control characteristic.
+    * @brief Get the handle for the value attribute of the control characteristic.
     */
     uint16_t getControlHandle(void) const {
         return controlPoint.getValueHandle();
@@ -88,7 +88,7 @@ public:
 
     /**
      * @brief This callback allows the DFU service to receive the initial trigger to
-     * handover control to the bootloader; but first the application is given a
+     * hand control over to the bootloader. First, the application is given a
      * chance to clean up.
      *
      * @param[in] params
@@ -96,7 +96,7 @@ public:
      */
     virtual void onDataWritten(const GattWriteCallbackParams *params) {
         if (params->handle == controlPoint.getValueHandle()) {
-            /* At present, writing anything will do the trick--this needs to be improved. */
+            /* At present, writing anything will do the trick - this needs to be improved. */
             if (handoverCallback) {
                 handoverCallback();
             }
@@ -112,22 +112,22 @@ protected:
 protected:
     BLE          &ble;
 
-    /**< Writing to the control characteristic triggers the handover to dfu-
-      *  bootloader. At present, writing anything will do the trick--this needs
+    /**< 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, but
-      *  is only a placeholder to mimic the corresponding characteristic in the
+    /**< 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 as service definitions change after
+      *  FOTA clients might get confused, because service definitions change after
       *  handing control over to the bootloader. */
     GattCharacteristic  packet;
 
     uint8_t             controlBytes[SIZEOF_CONTROL_BYTES];
     uint8_t             packetBytes[SIZEOF_PACKET_BYTES];
 
-    static ResetPrepare_t handoverCallback;  /**< application specific handover callback. */
+    static ResetPrepare_t handoverCallback;  /**< Application-specific handover callback. */
 };
 
 #endif /* #ifndef __BLE_DFU_SERVICE_H__*/