docs: add more documentation for the bluetooth apis.

more descriptions for some of the classes and a new
overview and pseudo-code example for using BT APIs
in the package summary.

6 files changed, 228 insertions, 68 deletions

diff --git a/core/java/android/bluetooth/BluetoothAdapter.java b/core/java/android/bluetooth/BluetoothAdapter.java
index ff48583..595156f 100644
--- a/core/java/android/bluetooth/BluetoothAdapter.java
+++ b/core/java/android/bluetooth/BluetoothAdapter.java
@@ -36,13 +36,30 @@ import java.util.Set;
 import java.util.UUID;
 
 /**
- * Represents the local Bluetooth adapter.
+ * Represents the local device Bluetooth adapter. The {@link BluetoothAdapter}
+ * lets you perform fundamental Bluetooth tasks, such as initiate
+ * device discovery, query a list of bonded (paired) devices,
+ * instantiate a {@link BluetoothDevice} using a known MAC address, and create
+ * a {@link BluetoothServerSocket} to listen for connection requests from other
+ * devices.
  *
- * <p>Use {@link #getDefaultAdapter} to get the default local Bluetooth
- * adapter.
+ * <p>To get a {@link BluetoothAdapter} representing the local Bluetooth
+ * adapter, call the static {@link #getDefaultAdapter} method.
+ * Fundamentally, this is your starting point for all
+ * Bluetooth actions. Once you have the local adapter, you can get a set of
+ * {@link BluetoothDevice} objects representing all paired devices with
+ * {@link #getBondedDevices()}; start device discovery with
+ * {@link #startDiscovery()}; or create a {@link BluetoothServerSocket} to
+ * listen for incoming connection requests with
+ * {@link #listenUsingRfcommWithServiceRecord(String,UUID)}.
  *
- * <p>Use the {@link BluetoothDevice} class for operations on remote Bluetooth
- * devices.
+ * <p class="note"><strong>Note:</strong>
+ * Most methods require the {@link android.Manifest.permission#BLUETOOTH}
+ * permission and some also require the
+ * {@link android.Manifest.permission#BLUETOOTH_ADMIN} permission.
+ *
+ * {@see BluetoothDevice}
+ * {@see BluetoothServerSocket}
  */
 public final class BluetoothAdapter {
     private static final String TAG = "BluetoothAdapter";
diff --git a/core/java/android/bluetooth/BluetoothClass.java b/core/java/android/bluetooth/BluetoothClass.java
index 6210380..bc06713 100644
--- a/core/java/android/bluetooth/BluetoothClass.java
+++ b/core/java/android/bluetooth/BluetoothClass.java
@@ -20,25 +20,37 @@ import android.os.Parcel;
 import android.os.Parcelable;
 
 /**
- * Represents a Bluetooth class.
+ * Represents a Bluetooth class, which describes general characteristics
+ * and capabilities of a device. For example, a Bluetooth class will
+ * specify the general device type such as a phone, a computer, or
+ * headset, and whether it's capable of services such as audio or telephony.
  *
- * <p>Bluetooth Class is a 32 bit field. The format of these bits is defined at
- *   http://www.bluetooth.org/Technical/AssignedNumbers/baseband.htm
- * (login required). This class contains that 32 bit field, and provides
- * constants and methods to determine which Service Class(es) and Device Class
- * are encoded in that field.
+ * <p>The Bluetooth class is useful as a hint to roughly describe a device (for example to
+ * show an icon in the UI), but does not reliably describe which Bluetooth
+ * profiles or services are actually supported by a device.
  *
- * <p>Every Bluetooth Class is composed of zero or more service classes, and
+ * <p>Every Bluetooth class is composed of zero or more service classes, and
  * exactly one device class. The device class is further broken down into major
  * and minor device class components.
  *
- * <p>Class is useful as a hint to roughly describe a device (for example to
- * show an icon in the UI), but does not reliably describe which Bluetooth
- * profiles or services are actually supported by a device. Accurate service
- * discovery is done through SDP requests.
+ * <p>{@link BluetoothClass} is useful as a hint to roughly describe a device
+ * (for example to show an icon in the UI), but does not reliably describe which
+ * Bluetooth profiles or services are actually supported by a device. Accurate
+ * service discovery is done through SDP requests, which are automatically
+ * performed when creating an RFCOMM socket with {@link
+ * BluetoothDevice#createRfcommSocketToServiceRecord(UUID)} and {@link
+ * BluetoothAdapter#listenUsingRfcommWithServiceRecord(String,UUID)}</p>
  *
  * <p>Use {@link BluetoothDevice#getBluetoothClass} to retrieve the class for
  * a remote device.
+ *
+ * <!--
+ * The Bluetooth class is a 32 bit field. The format of these bits is defined at
+ * http://www.bluetooth.org/Technical/AssignedNumbers/baseband.htm
+ * (login required). This class contains that 32 bit field, and provides
+ * constants and methods to determine which Service Class(es) and Device Class
+ * are encoded in that field.
+ * -->
  */
 public final class BluetoothClass implements Parcelable {
     /**
@@ -91,7 +103,7 @@ public final class BluetoothClass implements Parcelable {
     }
 
     /**
-     * Bluetooth service classes.
+     * Defines all service class constants.
      * <p>Each {@link BluetoothClass} encodes zero or more service classes.
      */
     public static final class Service {
@@ -109,7 +121,8 @@ public final class BluetoothClass implements Parcelable {
     }
 
     /**
-     * Return true if the specified service class is supported by this class.
+     * Return true if the specified service class is supported by this
+     * {@link BluetoothClass}.
      * <p>Valid service classes are the public constants in
      * {@link BluetoothClass.Service}. For example, {@link
      * BluetoothClass.Service#AUDIO}.
@@ -122,17 +135,22 @@ public final class BluetoothClass implements Parcelable {
     }
 
     /**
-     * Bluetooth device classes.
+     * Defines all device class constants.
      * <p>Each {@link BluetoothClass} encodes exactly one device class, with
      * major and minor components.
      * <p>The constants in {@link
      * BluetoothClass.Device} represent a combination of major and minor
-     * components (the complete device class). The constants in {@link
-     * BluetoothClass.Device.Major} represent just the major device classes.
+     * device components (the complete device class). The constants in {@link
+     * BluetoothClass.Device.Major} represent only major device classes.
+     * <p>See {@link BluetoothClass.Service} for service class constants.
      */
     public static class Device {
         private static final int BITMASK               = 0x1FFC;
 
+        /**
+         * Defines all major device class constants.
+         * <p>See {@link BluetoothClass.Device} for minor classes.
+         */
         public static class Major {
             private static final int BITMASK           = 0x1F00;
 
@@ -215,7 +233,7 @@ public final class BluetoothClass implements Parcelable {
     }
 
     /**
-     * Return the major device class component of this Bluetooth class.
+     * Return the major device class component of this {@link BluetoothClass}.
      * <p>Values returned from this function can be compared with the
      * public constants in {@link BluetoothClass.Device.Major} to determine
      * which major class is encoded in this Bluetooth class.
diff --git a/core/java/android/bluetooth/BluetoothDevice.java b/core/java/android/bluetooth/BluetoothDevice.java
index 849e6c7..6cb9770 100644
--- a/core/java/android/bluetooth/BluetoothDevice.java
+++ b/core/java/android/bluetooth/BluetoothDevice.java
@@ -31,16 +31,31 @@ import java.io.UnsupportedEncodingException;
 import java.util.UUID;
 
 /**
- * Represents a remote Bluetooth device.
- *
- * <p>Use {@link BluetoothAdapter#getRemoteDevice} to create a {@link
- * BluetoothDevice}.
+ * Represents a remote Bluetooth device. A {@link BluetoothDevice} lets you
+ * create a connection with the repective device or query information about
+ * it, such as the name, address, class, and bonding state.
  *
  * <p>This class is really just a thin wrapper for a Bluetooth hardware
  * address. Objects of this class are immutable. Operations on this class
  * are performed on the remote Bluetooth hardware address, using the
  * {@link BluetoothAdapter} that was used to create this {@link
  * BluetoothDevice}.
+ *
+ * <p>To get a {@link BluetoothDevice}, use
+ * {@link BluetoothAdapter#getRemoteDevice(String)
+ * BluetoothAdapter.getRemoteDevice(String)} to create one representing a device
+ * of a known MAC address (which you can get through device discovery with
+ * {@link BluetoothAdapter}) or get one from the set of bonded devices
+ * returned by {@link BluetoothAdapter#getBondedDevices()
+ * BluetoothAdapter.getBondedDevices()}. You can then open a
+ * {@link BluetoothSocket} for communciation with the remote device, using
+ * {@link #createRfcommSocketToServiceRecord(UUID)}.
+ *
+ * <p class="note"><strong>Note:</strong>
+ * Requires the {@link android.Manifest.permission#BLUETOOTH} permission.
+ *
+ * {@see BluetoothAdapter}
+ * {@see BluetoothSocket}
  */
 public final class BluetoothDevice implements Parcelable {
     private static final String TAG = "BluetoothDevice";
diff --git a/core/java/android/bluetooth/BluetoothServerSocket.java b/core/java/android/bluetooth/BluetoothServerSocket.java
index 605bdc1..1b23f6c 100644
--- a/core/java/android/bluetooth/BluetoothServerSocket.java
+++ b/core/java/android/bluetooth/BluetoothServerSocket.java
@@ -27,29 +27,31 @@ import java.io.IOException;
  * <p>The interface for Bluetooth Sockets is similar to that of TCP sockets:
  * {@link java.net.Socket} and {@link java.net.ServerSocket}. On the server
  * side, use a {@link BluetoothServerSocket} to create a listening server
- * socket. It will return a new, connected {@link BluetoothSocket} on an
- * accepted connection. On the client side, use the same
- * {@link BluetoothSocket} object to both intiate the outgoing connection,
- * and to manage the connected socket.
+ * socket. When a connection is accepted by the {@link BluetoothServerSocket},
+ * it will return a new {@link BluetoothSocket} to manage the connection.
+ * On the client side, use a single {@link BluetoothSocket} to both intiate
+ * an outgoing connection and to manage the connection.
  *
- * <p>The most common type of Bluetooth Socket is RFCOMM. RFCOMM is a
- * connection orientated, streaming transport over Bluetooth. It is also known
- * as the Serial Port Profile (SPP).
+ * <p>The most common type of Bluetooth socket is RFCOMM, which is the type
+ * supported by the Android APIs. RFCOMM is a connection-oriented, streaming
+ * transport over Bluetooth. It is also known as the Serial Port Profile (SPP).
  *
- * <p>Use {@link BluetoothDevice#createRfcommSocketToServiceRecord} to create
- * a new {@link BluetoothSocket} ready for an outgoing connection to a remote
- * {@link BluetoothDevice}.
+ * <p>To create a listenting {@link BluetoothServerSocket} that's ready for
+ * incoming connections, use
+ * {@link BluetoothAdapter#listenUsingRfcommWithServiceRecord
+ * BluetoothAdapter.listenUsingRfcommWithServiceRecord()}. Then call
+ * {@link #accept()} to listen for incoming connection requests. This call
+ * will block until a connection is established, at which point, it will return
+ * a {@link BluetoothSocket} to manage the connection.
  *
- * <p>Use {@link BluetoothAdapter#listenUsingRfcommWithServiceRecord} to
- * create a listening {@link BluetoothServerSocket} ready for incoming
- * connections to the local {@link BluetoothAdapter}.
- *
- * <p>{@link BluetoothSocket} and {@link BluetoothServerSocket} are thread
+ * <p>{@link BluetoothServerSocket} is thread
  * safe. In particular, {@link #close} will always immediately abort ongoing
- * operations and close the socket.
+ * operations and close the server socket.
+ *
+ * <p class="note"><strong>Note:</strong>
+ * Requires the {@link android.Manifest.permission#BLUETOOTH} permission.
  *
- * <p>All methods on a {@link BluetoothServerSocket} require
- * {@link android.Manifest.permission#BLUETOOTH}
+ * {@see BluetoothSocket}
  */
 public final class BluetoothServerSocket implements Closeable {
 
diff --git a/core/java/android/bluetooth/BluetoothSocket.java b/core/java/android/bluetooth/BluetoothSocket.java
index 7e72590..dbcc758 100644
--- a/core/java/android/bluetooth/BluetoothSocket.java
+++ b/core/java/android/bluetooth/BluetoothSocket.java
@@ -33,29 +33,41 @@ import java.util.concurrent.locks.ReentrantReadWriteLock;
  * <p>The interface for Bluetooth Sockets is similar to that of TCP sockets:
  * {@link java.net.Socket} and {@link java.net.ServerSocket}. On the server
  * side, use a {@link BluetoothServerSocket} to create a listening server
- * socket. It will return a new, connected {@link BluetoothSocket} on an
- * accepted connection. On the client side, use the same
- * {@link BluetoothSocket} object to both intiate the outgoing connection,
- * and to manage the connected socket.
+ * socket. When a connection is accepted by the {@link BluetoothServerSocket},
+ * it will return a new {@link BluetoothSocket} to manage the connection.
+ * On the client side, use a single {@link BluetoothSocket} to both intiate
+ * an outgoing connection and to manage the connection.
  *
- * <p>The most common type of Bluetooth Socket is RFCOMM. RFCOMM is a
- * connection orientated, streaming transport over Bluetooth. It is also known
- * as the Serial Port Profile (SPP).
+ * <p>The most common type of Bluetooth socket is RFCOMM, which is the type
+ * supported by the Android APIs. RFCOMM is a connection-oriented, streaming
+ * transport over Bluetooth. It is also known as the Serial Port Profile (SPP).
  *
- * <p>Use {@link BluetoothDevice#createRfcommSocketToServiceRecord} to create
- * a new {@link BluetoothSocket} ready for an outgoing connection to a remote
- * {@link BluetoothDevice}.
+ * <p>To create a {@link BluetoothSocket} for connecting to a known device, use
+ * {@link BluetoothDevice#createRfcommSocketToServiceRecord
+ * BluetoothDevice.createRfcommSocketToServiceRecord()}.
+ * Then call {@link #connect()} to attempt a connection to the remote device.
+ * This call will block until a connection is established or the connection
+ * fails.
  *
- * <p>Use {@link BluetoothAdapter#listenUsingRfcommWithServiceRecord} to
- * create a listening {@link BluetoothServerSocket} ready for incoming
- * connections to the local {@link BluetoothAdapter}.
+ * <p>To create a {@link BluetoothSocket} as a server (or "host"), see the
+ * {@link BluetoothServerSocket} documentation.
  *
- * <p>{@link BluetoothSocket} and {@link BluetoothServerSocket} are thread
+ * <p>Once the socket is connected, whether initiated as a client or accepted
+ * as a server, open the IO streams by calling {@link #getInputStream} and
+ * {@link #getOutputStream} in order to retrieve {@link java.io.InputStream}
+ * and {@link java.io.OutputStream} objects, respectively, which are
+ * automatically connected to the socket.
+ *
+ * <p>{@link BluetoothSocket} is thread
  * safe. In particular, {@link #close} will always immediately abort ongoing
  * operations and close the socket.
  *
- * <p>All methods on a {@link BluetoothSocket} require
- * {@link android.Manifest.permission#BLUETOOTH}
+ * <p class="note"><strong>Note:</strong>
+ * Requires the {@link android.Manifest.permission#BLUETOOTH} permission.
+ *
+ * {@see BluetoothServerSocket}
+ * {@see java.io.InputStream}
+ * {@see java.io.OutputStream}
  */
 public final class BluetoothSocket implements Closeable {
     private static final String TAG = "BluetoothSocket";
diff --git a/core/java/android/bluetooth/package.html b/core/java/android/bluetooth/package.html
index 79abf0c..4f0755e 100644
--- a/core/java/android/bluetooth/package.html
+++ b/core/java/android/bluetooth/package.html
@@ -1,13 +1,109 @@
 <HTML>
 <BODY>
-Provides classes that manage Bluetooth functionality on the device.
-<p>
-The Bluetooth APIs allow applications can connect and disconnect headsets, or scan 
-for other kinds of Bluetooth devices and pair them. Further control includes the 
-ability to write and modify the local Service Discovery Protocol (SDP) database, 
-query the SDP database of other Bluetooth devices, establish RFCOMM 
-channels/sockets on Android, and connect to specified sockets on other devices.
+Provides classes that manage Bluetooth functionality, such as scanning for
+devices, connecting with devices, and managing data transfer between devices.
+
+<p>The Bluetooth APIs let applications:</p>
+<ul>
+  <li>Scan for other Bluetooth devices</li>
+  <li>Query the local Bluetooth adapter for paired Bluetooth devices</li>
+  <li>Establish RFCOMM channels/sockets</li>
+  <li>Connect to specified sockets on other devices</li>
+  <li>Transfer data to and from other devices</li>
+</ul>
+
+<p class="note"><strong>Note:</strong>
+To perform Bluetooth communication using these APIs, an application must
+declare the {@link android.Manifest.permission#BLUETOOTH} permission. Some
+additional functionality, such as requesting device discovery and
+pairing also requires the {@link android.Manifest.permission#BLUETOOTH_ADMIN}
+permission.
 </p>
-<p>Remember, not all Android devices are guaranteed to have Bluetooth functionality.</p>
+
+<h3>Overview</h3>
+
+<p>Here's a basic introduction to the Bluetooth classes:</p>
+<dl>
+  <dt>{@link android.bluetooth.BluetoothAdapter}</dt>
+  <dd>This represents the local Bluetooth adapter, which is essentially the
+  entry-point to performing any interaction with Bluetooth. With it, you can
+  discover other Bluetooth devices, query a list of bonded (paired) devices,
+  initialize a {@link android.bluetooth.BluetoothDevice} using a known MAC
+  address, and create a {@link android.bluetooth.BluetoothServerSocket} to
+  listen for communications from other devices.</dd>
+
+  <dt>{@link android.bluetooth.BluetoothDevice}</dt>
+  <dd>This represents a remote Bluetooth device. Use this to request a
+  connection with a remote device through a
+  {@link android.bluetooth.BluetoothSocket}
+  or query information about the device such as its name, address, class, and
+  bonding state.</dd>
+
+  <dt>{@link android.bluetooth.BluetoothSocket}</dt>
+  <dd>This represents the interface for a Bluetooth socket
+  (similar to a TCP client-side {@link java.net.Socket}). This is the
+  connection point that allows an app to transfer data with another Bluetooth
+  device via {@link java.io.InputStream} and {@link java.io.OutputStream}.</dd>
+  <dt>{@link android.bluetooth.BluetoothServerSocket}</dt>
+
+  <dd>This represents an open server socket that listens for incoming requests
+  (similar to a TCP server-side {@link java.net.ServerSocket}).
+  When attempting to connect two Android devices, one device will need to open
+  a server socket with this class. When a connection is accepted, a new
+  {@link android.bluetooth.BluetoothSocket} will be returned,
+  which can be used to manage the connection and transfer data.</dd>
+
+  <dt>{@link android.bluetooth.BluetoothClass}</dt>
+  <dd>This represents the Bluetooth class for a device which describes general
+  characteristics and capabilities of a device. This class and its subclasses
+  don't provide any actual functionality. The sub-classes are entirely composed
+  of constants for the device and service class definitions.</dd>
+</dl>
+
+
+<h3>Example Procedure</h3>
+
+<p>For example, here's an pseudo-code procedure for discovering and
+connecting a remote device, and transfering data:</p>
+
+<ol>
+  <li>Register a {@link android.content.BroadcastReceiver} that accepts the
+  {@link android.bluetooth.BluetoothDevice#ACTION_FOUND} Intent.</li>
+  <li>Call {@link android.bluetooth.BluetoothAdapter#getDefaultAdapter} to
+  retrieve the Android system's local
+  {@link android.bluetooth.BluetoothAdapter}.</li>
+  <li>Call {@link android.bluetooth.BluetoothAdapter#startDiscovery()
+  BluetoothAdapter.startDiscovery()} to scan for local devices. This is where
+  the BroadcastReceiver comes in; Android now scans for devices and will
+  broadcast the {@link android.bluetooth.BluetoothDevice#ACTION_FOUND} Intent
+  for each remote device discovered. The
+  {@link android.content.BroadcastReceiver}
+  you created will receive each Intent.</li>
+  <li>The {@link android.bluetooth.BluetoothDevice#ACTION_FOUND} Intent
+  includes the {@link android.bluetooth.BluetoothDevice#EXTRA_DEVICE}
+  Parcelable extra, which is a {@link android.bluetooth.BluetoothDevice}
+  object. Extract this from the Intent and call
+  {@link android.bluetooth.BluetoothDevice#createRfcommSocketToServiceRecord(java.util.UUID)
+  BluetoothDevice.createRfcommSocketToServiceRecord()}
+  to open a {@link android.bluetooth.BluetoothSocket} with a chosen
+  remote device.</li>
+  <li>Call {@link android.bluetooth.BluetoothSocket#connect()
+  BluetoothSocket.connect()} to connect with the remote device.</li>
+  <li>When successfully connected, call
+  {@link android.bluetooth.BluetoothSocket#getInputStream()
+  BluetoothSocket.getInputStream()} and/or
+  {@link android.bluetooth.BluetoothSocket#getOutputStream()
+  BluetoothSocket.getOutputStream()} to retreive an
+  {@link java.io.InputStream} and {@link java.io.OutputStream}, respectively,
+  which are hooked into the socket.</li>
+  <li>Use {@link java.io.InputStream#read(byte[]) InputStream.read()} and
+  {@link java.io.OutputStream#write(byte[]) OutputStream.write()} to transfer
+  data.</li>
+</ol>
+
+
+
+<p class="note"><strong>Note:</strong>
+Not all Android devices are guaranteed to have Bluetooth functionality.</p>
 </BODY>
 </HTML>