Bluetooth API: improve discovery

chrome/common/extensions/api/experimental_bluetooth.idl

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // Bluetooth API.
 // TODO(bryeung): mark this API as ChromeOS only (see crbug.com/119398).
 
 namespace experimental.bluetooth {
   dictionary Device {
     // The address of the device, in the format 'XX:XX:XX:XX:XX:XX'.
@@ skipping 172 matching lines @@
         OutOfBandPairingDataCallback callback);
 
     // Set the Out of Band Pairing data for a remote device.
     // Any previous Out Of Band Pairing Data for this device is overwritten.
     // |options|  : The options for this function.
     // |callback| : Called to indicate success or failure.
     static void setOutOfBandPairingData(SetOutOfBandPairingDataOptions options,
                                         optional ResultCallback callback);
 
     // Start discovery. Discovered devices will be returned via the
-    // |onDeviceDiscovered| callback. Note that discovery can be resource
-    // intensive. stopDiscovery should be called as soon as is convenient.
+    // |onDeviceDiscovered| callback.  Discovery will fail to start if it is
+    // already in progress.  Discovery can be resource intensive: stopDiscovery
+    // should be called as soon as possible.
     // |options|  : The options for this function.
     // |callback| : Called to indicate success or failure.
     static void startDiscovery(
         StartDiscoveryOptions options,
         optional ResultCallback callback);
 
     // Stop discovery.
     // |callback| : Called to indicate success or failure.
     static void stopDiscovery(
         optional ResultCallback callback);
   };
 
   interface Events {
     // Fired when the availability of bluetooth on the system changes.
     // |available| : True if bluetooth is available, false otherwise.
     static void onAvailabilityChanged(boolean available);
 
     // Fired when the power state of bluetooth on the system changes.
     // |powered| : True if bluetooth is powered, false otherwise.
     static void onPowerChanged(boolean has_power);
 
     // Fired when the discovering state of the system changes.
     // |discovering| : True if the system is currently in discovery mode, false
     //                 otherwise.
     static void onDiscoveringChanged(boolean discovering);
   };
 };