Update chrome.bluetooth API docs to be clearer on the correct way to use it.

chrome/common/extensions/api/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.
 
 // Use the <code>chrome.bluetooth</code> API to connect to a Bluetooth
-// device.
+// device. All functions report failures via chrome.runtime.lastError.
 namespace bluetooth {
   dictionary AdapterState {
     // The address of the adapter, in the format 'XX:XX:XX:XX:XX:XX'.
     DOMString address;
 
     // The human-readable name of the adapter.
     DOMString name;
 
     // Indicates whether or not the adapter has power.
     boolean powered;
@@ skipping 209 matching lines @@
     // |callback| : Called to indicate success or failure.
     static void connect(ConnectOptions options,
                         ResultCallback callback);
 
     // Close a Bluetooth connection.
     // |options|  : The options for this function.
     // |callback| : Called to indicate success or failure.
     static void disconnect(DisconnectOptions options,
                            optional ResultCallback callback);
 
-    // Read data from a Bluetooth connection.
+    // Read data from a Bluetooth connection. The |callback| will be called
+    // with the current data in the buffer even if it is empty. This function
+    // should be polled to read incoming data.
     // |options|  : The options for this function.
-    // |callback| : Called with the data when it is available.
+    // |callback| : Called with the data read from the socket buffer.
     static void read(ReadOptions options,
                      DataCallback callback);
 
     // Write data to a Bluetooth connection.
     // |options|  : The options for this function.
     // |callback| : Called with the number of bytes written.
     static void write(WriteOptions options,
                       optional SizeCallback callback);
 
     // Get the local Out of Band Pairing data.
@@ skipping 27 matching lines @@
   interface Events {
     // Fired when the state of the Bluetooth adapter changes.
     // |state| : The new state of the adapter.
     static void onAdapterStateChanged(AdapterState state);
 
     // Fired when a connection has been made for a registered profile.
     // |socket| : The socket for the connection.
     static void onConnection(Socket socket);
   };
 };