From beef809fa89a5e7955a4c25cf70e00adbcf2e24e Mon Sep 17 00:00:00 2001
From: Scott Main <smain@google.com>
Date: Tue, 3 Nov 2009 18:17:59 -0800
Subject: 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.
---
 .../java/android/bluetooth/BluetoothClass.java     | 52 +++++++++++++++-------
 1 file changed, 35 insertions(+), 17 deletions(-)

(limited to 'framework/java/android/bluetooth/BluetoothClass.java')

diff --git a/framework/java/android/bluetooth/BluetoothClass.java b/framework/java/android/bluetooth/BluetoothClass.java
index 6210380595..bc06713058 100644
--- a/framework/java/android/bluetooth/BluetoothClass.java
+++ b/framework/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.
-- 
cgit v1.2.3