Diff: ble/ServiceDiscovery.h

Revision:

910:77ca47abaecf

Parent:

716:11b41f651697

Child:

912:f728aa46e7df

--- a/ble/ServiceDiscovery.h	Thu Nov 26 12:52:02 2015 +0000
+++ b/ble/ServiceDiscovery.h	Thu Nov 26 12:52:02 2015 +0000
@@ -31,22 +31,22 @@
      */
 
     /**
-     * Callback type for when a matching Service is found during service-
+     * Callback type for when a matching service is found during service-
      * discovery. The receiving function is passed in a pointer to a
-     * DiscoveredService object which will remain valid for the lifetime of the
+     * DiscoveredService object, which will remain valid for the lifetime of the
      * callback. Memory for this object is owned by the BLE_API eventing
      * framework. The application can safely make a persistent shallow-copy of
-     * this object in order to work with the service beyond the callback.
+     * this object to work with the service beyond the callback.
      */
     typedef void (*ServiceCallback_t)(const DiscoveredService *);
 
     /**
-     * Callback type for when a matching Characteristic is found during service-
+     * Callback type for when a matching characteristic is found during service-
      * discovery. The receiving function is passed in a pointer to a
-     * DiscoveredCharacteristic object which will remain valid for the lifetime
+     * DiscoveredCharacteristic object, which will remain valid for the lifetime
      * of the callback. Memory for this object is owned by the BLE_API eventing
      * framework. The application can safely make a persistent shallow-copy of
-     * this object in order to work with the characteristic beyond the callback.
+     * this object to work with the characteristic beyond the callback.
      */
     typedef void (*CharacteristicCallback_t)(const DiscoveredCharacteristic *);
 
@@ -59,47 +59,47 @@
     /**
      * Launch service discovery. Once launched, service discovery will remain
      * active with callbacks being issued back into the application for matching
-     * services/characteristics. isActive() can be used to determine status; and
-     * a termination callback (if setup) will be invoked at the end. Service
-     * discovery can be terminated prematurely if needed using terminate().
+     * services or characteristics. isActive() can be used to determine status, and
+     * a termination callback (if set up) will be invoked at the end. Service
+     * discovery can be terminated prematurely, if needed, using terminate().
      *
      * @param  connectionHandle
      *           Handle for the connection with the peer.
      * @param  sc
-     *           This is the application callback for matching service. Taken as
+     *           This is the application callback for a matching service. Taken as
      *           NULL by default. Note: service discovery may still be active
      *           when this callback is issued; calling asynchronous BLE-stack
      *           APIs from within this application callback might cause the
      *           stack to abort service discovery. If this becomes an issue, it
-     *           may be better to make local copy of the discoveredService and
+     *           may be better to make a local copy of the discoveredService and
      *           wait for service discovery to terminate before operating on the
      *           service.
      * @param  cc
-     *           This is the application callback for matching characteristic.
+     *           This is the application callback for a matching characteristic.
      *           Taken as NULL by default. Note: service discovery may still be
      *           active when this callback is issued; calling asynchronous
      *           BLE-stack APIs from within this application callback might cause
      *           the stack to abort service discovery. If this becomes an issue,
-     *           it may be better to make local copy of the discoveredCharacteristic
+     *           it may be better to make a local copy of the discoveredCharacteristic
      *           and wait for service discovery to terminate before operating on the
      *           characteristic.
      * @param  matchingServiceUUID
-     *           UUID based filter for specifying a service in which the application is
+     *           UUID-based filter for specifying a service in which the application is
      *           interested. By default it is set as the wildcard UUID_UNKNOWN,
      *           in which case it matches all services. If characteristic-UUID
      *           filter (below) is set to the wildcard value, then a service
      *           callback will be invoked for the matching service (or for every
      *           service if the service filter is a wildcard).
      * @param  matchingCharacteristicUUIDIn
-     *           UUID based filter for specifying characteristic in which the application
+     *           UUID-based filter for specifying a characteristic in which the application
      *           is interested. By default it is set as the wildcard UUID_UKNOWN
      *           to match against any characteristic. If both service-UUID
-     *           filter and characteristic-UUID filter are used with non- wildcard
+     *           filter and characteristic-UUID filter are used with non-wildcard
      *           values, then only a single characteristic callback is
      *           invoked for the matching characteristic.
      *
      * @note     Using wildcard values for both service-UUID and characteristic-
-     *           UUID will result in complete service discovery--callbacks being
+     *           UUID will result in complete service discovery: callbacks being
      *           called for every service and characteristic.
      *
      * @note     Providing NULL for the characteristic callback will result in
@@ -122,13 +122,13 @@
     virtual bool        isActive(void) const = 0;
 
     /**
-     * Terminate an ongoing service-discovery. This should result in an
-     * invocation of the TerminationCallback if service-discovery is active.
+     * Terminate an ongoing service discovery. This should result in an
+     * invocation of the TerminationCallback if service discovery is active.
      */
     virtual void        terminate(void) = 0;
 
     /**
-     * Setup callback to be invoked when service discovery is terminated.
+     * Set up a callback to be invoked when service discovery is terminated.
      */
     virtual void        onTermination(TerminationCallback_t callback) = 0;