am 4570dfa2: am 7b0463a9: am ed2a70d6: docs: add the Bluetooth developer guide, and make some revisions to the BT javadocs

Merge commit '4570dfa2016fa32b6f7b29aabadb9d708482b94d'

* commit '4570dfa2016fa32b6f7b29aabadb9d708482b94d':
  docs: add the Bluetooth developer guide,

core/java/android/bluetooth/BluetoothAdapter.java

@@ -370,9 +370,17 @@ public final class BluetoothAdapter {
     }
 
     /**
-     * Turn on the local Bluetooth adapter.
+     * Turn on the local Bluetooth adapter—do not use without explicit
+     * user action to turn on Bluetooth.
      * <p>This powers on the underlying Bluetooth hardware, and starts all
      * Bluetooth system services.
+     * <p class="caution"><strong>Bluetooth should never be enabled without
+     * direct user consent</strong>. If you want to turn on Bluetooth in order
+     * to create a wireless connection, you should use the {@link
+     * #ACTION_REQUEST_ENABLE} Intent, which will raise a dialog that requests
+     * user permission to turn on Bluetooth. The {@link #enable()} method is
+     * provided only for applications that include a user interface for changing
+     * system settings, such as a "power manager" app.</p>
      * <p>This is an asynchronous call: it will return immediately, and
      * clients should listen for {@link #ACTION_STATE_CHANGED}
      * to be notified of subsequent adapter state changes. If this call returns
@@ -382,7 +390,8 @@ public final class BluetoothAdapter {
      * #STATE_ON}. If this call returns false then there was an
      * immediate problem that will prevent the adapter from being turned on -
      * such as Airplane mode, or the adapter is already turned on.
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}
+     * <p>Requires the {@link android.Manifest.permission#BLUETOOTH_ADMIN}
+     * permission
      *
      * @return true to indicate adapter startup has begun, or false on
      *         immediate error
@@ -395,9 +404,14 @@ public final class BluetoothAdapter {
     }
 
     /**
-     * Turn off the local Bluetooth adapter.
+     * Turn off the local Bluetooth adapter&mdash;do not use without explicit
+     * user action to turn off Bluetooth.
      * <p>This gracefully shuts down all Bluetooth connections, stops Bluetooth
      * system services, and powers down the underlying Bluetooth hardware.
+     * <p class="caution"><strong>Bluetooth should never be disbled without
+     * direct user consent</strong>. The {@link #disable()} method is
+     * provided only for applications that include a user interface for changing
+     * system settings, such as a "power manager" app.</p>
      * <p>This is an asynchronous call: it will return immediately, and
      * clients should listen for {@link #ACTION_STATE_CHANGED}
      * to be notified of subsequent adapter state changes. If this call returns
@@ -407,7 +421,8 @@ public final class BluetoothAdapter {
      * #STATE_ON}. If this call returns false then there was an
      * immediate problem that will prevent the adapter from being turned off -
      * such as the adapter already being turned off.
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}
+     * <p>Requires the {@link android.Manifest.permission#BLUETOOTH_ADMIN}
+     * permission
      *
      * @return true to indicate adapter shutdown has begun, or false on
      *         immediate error

core/java/android/bluetooth/BluetoothClass.java

@@ -25,10 +25,6 @@ import android.os.Parcelable;
  * 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>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
  * exactly one device class. The device class is further broken down into major
  * and minor device class components.