diff --git a/core/java/android/bluetooth/BluetoothA2dp.java b/core/java/android/bluetooth/BluetoothA2dp.java
index 61b43036ef3d1..231f5920be56f 100644
--- a/core/java/android/bluetooth/BluetoothA2dp.java
+++ b/core/java/android/bluetooth/BluetoothA2dp.java
@@ -50,15 +50,18 @@ public final class BluetoothA2dp implements BluetoothProfile {
      * profile.
      *
      * <p>This intent will have 3 extras:
-     * {@link #EXTRA_STATE} - The current state of the profile.
-     * {@link #EXTRA_PREVIOUS_STATE}- The previous state of the profile
-     * {@link BluetoothDevice#EXTRA_DEVICE} - The remote device.
+     * <ul>
+     *   <li> {@link #EXTRA_STATE} - The current state of the profile. </li>
+     *   <li> {@link #EXTRA_PREVIOUS_STATE}- The previous state of the profile.</li>
+     *   <li> {@link BluetoothDevice#EXTRA_DEVICE} - The remote device. </li>
+     * </ul>
      *
      * {@link #EXTRA_STATE} or {@link #EXTRA_PREVIOUS_STATE} can be any of
      * {@link #STATE_DISCONNECTED}, {@link #STATE_CONNECTING},
      * {@link #STATE_CONNECTED}, {@link #STATE_DISCONNECTING}.
      *
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.
+     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission to
+     * receive.
      */
     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
     public static final String ACTION_CONNECTION_STATE_CHANGED =
@@ -69,14 +72,17 @@ public final class BluetoothA2dp implements BluetoothProfile {
      * profile.
      *
      * <p>This intent will have 3 extras:
-     * {@link #EXTRA_STATE} - The current state of the profile.
-     * {@link #EXTRA_PREVIOUS_STATE}- The previous state of the profile
-     * {@link BluetoothDevice#EXTRA_DEVICE} - The remote device.
+     * <ul>
+     *   <li> {@link #EXTRA_STATE} - The current state of the profile. </li>
+     *   <li> {@link #EXTRA_PREVIOUS_STATE}- The previous state of the profile. </li>
+     *   <li> {@link BluetoothDevice#EXTRA_DEVICE} - The remote device. <li/>
+     * </ul>
      *
      * {@link #EXTRA_STATE} or {@link #EXTRA_PREVIOUS_STATE} can be any of
      * {@link #STATE_PLAYING}, {@link #STATE_NOT_PLAYING},
      *
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.
+     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission to
+     * receive.
      */
     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
     public static final String ACTION_PLAYING_STATE_CHANGED =
@@ -258,7 +264,7 @@ public final class BluetoothA2dp implements BluetoothProfile {
     /**
      * Check if A2DP profile is streaming music.
      *
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH}
+     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.
      *
      * @param device BluetoothDevice device
      */
@@ -281,11 +287,12 @@ public final class BluetoothA2dp implements BluetoothProfile {
      *
      * <p> This API will return false in scenarios like the A2DP
      * device is not in connected state etc. When this API returns,
-     * true, it is guaranteed that {@link #ACTION_SINK_STATE_CHANGED}
+     * true, it is guaranteed that {@link #ACTION_CONNECTION_STATE_CHANGED}
      * intent will be broadcasted with the state. Users can get the
      * state of the A2DP device from this intent.
      *
      * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}
+     * permission.
      *
      * @param device Remote A2DP sink
      * @return false on immediate error,
diff --git a/core/java/android/bluetooth/BluetoothDevice.java b/core/java/android/bluetooth/BluetoothDevice.java
index 24217d7dc011d..254e2f813a043 100644
--- a/core/java/android/bluetooth/BluetoothDevice.java
+++ b/core/java/android/bluetooth/BluetoothDevice.java
@@ -748,6 +748,15 @@ public final class BluetoothDevice implements Parcelable {
      * outgoing connection to this remote device on given channel.
      * <p>The remote device will be authenticated and communication on this
      * socket will be encrypted.
+     * <p> Use this socket only if an authenticated socket link is possible.
+     * Authentication refers to the authentication of the link key to
+     * prevent man-in-the-middle type of attacks.
+     * For example, for Bluetooth 2.1 devices, if any of the devices does not
+     * have an input and output capability or just has the ability to
+     * display a numeric key, a secure socket connection is not possible.
+     * In such a case, use {#link createInsecureRfcommSocket}.
+     * For more details, refer to the Security Model section 5.2 (vol 3) of
+     * Bluetooth Core Specification version 2.1 + EDR.
      * <p>Use {@link BluetoothSocket#connect} to initiate the outgoing
      * connection.
      * <p>Valid RFCOMM channels are in range 1 to 30.
@@ -775,6 +784,15 @@ public final class BluetoothDevice implements Parcelable {
      * determine which channel to connect to.
      * <p>The remote device will be authenticated and communication on this
      * socket will be encrypted.
+     * <p> Use this socket only if an authenticated socket link is possible.
+     * Authentication refers to the authentication of the link key to
+     * prevent man-in-the-middle type of attacks.
+     * For example, for Bluetooth 2.1 devices, if any of the devices does not
+     * have an input and output capability or just has the ability to
+     * display a numeric key, a secure socket connection is not possible.
+     * In such a case, use {#link createInsecureRfcommSocketToServiceRecord}.
+     * For more details, refer to the Security Model section 5.2 (vol 3) of
+     * Bluetooth Core Specification version 2.1 + EDR.
      * <p>Hint: If you are connecting to a Bluetooth serial board then try
      * using the well-known SPP UUID 00001101-0000-1000-8000-00805F9B34FB.
      * However if you are connecting to an Android peer then please generate
diff --git a/core/java/android/bluetooth/BluetoothHeadset.java b/core/java/android/bluetooth/BluetoothHeadset.java
index a7e45182aa4f3..f5f6092be1a10 100644
--- a/core/java/android/bluetooth/BluetoothHeadset.java
+++ b/core/java/android/bluetooth/BluetoothHeadset.java
@@ -52,15 +52,17 @@ public final class BluetoothHeadset implements BluetoothProfile {
      * profile.
      *
      * <p>This intent will have 3 extras:
-     * {@link #EXTRA_STATE} - The current state of the profile.
-     * {@link #EXTRA_PREVIOUS_STATE}- The previous state of the profile
-     * {@link BluetoothDevice#EXTRA_DEVICE} - The remote device.
-     *
+     * <ul>
+     *   <li> {@link #EXTRA_STATE} - The current state of the profile. </li>
+     *   <li> {@link #EXTRA_PREVIOUS_STATE}- The previous state of the profile. </li>
+     *   <li> {@link BluetoothDevice#EXTRA_DEVICE} - The remote device. </li>
+     * </ul>
      * {@link #EXTRA_STATE} or {@link #EXTRA_PREVIOUS_STATE} can be any of
      * {@link #STATE_DISCONNECTED}, {@link #STATE_CONNECTING},
      * {@link #STATE_CONNECTED}, {@link #STATE_DISCONNECTING}.
      *
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.
+     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission to
+     * receive.
      */
     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
     public static final String ACTION_CONNECTION_STATE_CHANGED =
@@ -71,14 +73,16 @@ public final class BluetoothHeadset implements BluetoothProfile {
      * A2DP profile.
      *
      * <p>This intent will have 3 extras:
-     * {@link #EXTRA_STATE} - The current state of the profile.
-     * {@link #EXTRA_PREVIOUS_STATE}- The previous state of the profile
-     * {@link BluetoothDevice#EXTRA_DEVICE} - The remote device.
-     *
+     * <ul>
+     *   <li> {@link #EXTRA_STATE} - The current state of the profile. </li>
+     *   <li> {@link #EXTRA_PREVIOUS_STATE}- The previous state of the profile. </li>
+     *   <li> {@link BluetoothDevice#EXTRA_DEVICE} - The remote device. </li>
+     * </ul>
      * {@link #EXTRA_STATE} or {@link #EXTRA_PREVIOUS_STATE} can be any of
      * {@link #STATE_AUDIO_CONNECTED}, {@link #STATE_AUDIO_DISCONNECTED},
      *
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.
+     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission
+     * to receive.
      */
     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
     public static final String ACTION_AUDIO_STATE_CHANGED =
@@ -90,16 +94,18 @@ public final class BluetoothHeadset implements BluetoothProfile {
      * vendor-specific event.
      *
      * <p>This intent will have 4 extras and 1 category.
-     * {@link BluetoothDevice#EXTRA_DEVICE} - The remote Bluetooth Device
-     * {@link #EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD} - The vendor specific
-     *                                                    command
-     * {@link #EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE} - The AT command
-     *                                                         type.
-     * Can be one of  {@link #AT_CMD_TYPE_READ}, {@link #AT_CMD_TYPE_TEST},
-     * or {@link #AT_CMD_TYPE_SET}, {@link #AT_CMD_TYPE_BASIC},
-     * {@link #AT_CMD_TYPE_ACTION}.
-     *
-     * {@link #EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_ARGS} - Command arguments.
+     * <ul>
+     *  <li> {@link BluetoothDevice#EXTRA_DEVICE} - The remote Bluetooth Device
+     *       </li>
+     *  <li> {@link #EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD} - The vendor
+     *       specific command </li>
+     *  <li> {@link #EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE} - The AT
+     *       command type which can be one of  {@link #AT_CMD_TYPE_READ},
+     *       {@link #AT_CMD_TYPE_TEST}, or {@link #AT_CMD_TYPE_SET},
+     *       {@link #AT_CMD_TYPE_BASIC},{@link #AT_CMD_TYPE_ACTION}. <li/>
+     *  <li> {@link #EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_ARGS} - Command
+     *       arguments. </li>
+     * </ul>
      *
      * The category is the Company ID of the vendor defining the
      * vendor-specific command. {@link BluetoothAssignedNumbers}
@@ -108,11 +114,13 @@ public final class BluetoothHeadset implements BluetoothProfile {
      * Category will be {@link #VENDOR_SPECIFIC_HEADSET_EVENT_COMPANY_ID_CATEGORY}.55
      *
      * <p> For example, an AT+XEVENT=foo,3 will get translated into
-     * EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD = +XEVENT
-     * EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE = AT_CMD_TYPE_SET
-     * EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_ARGS = foo, 3
-     *
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} to receive.
+     * <ul>
+     *   <li> EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD = +XEVENT </li>
+     *   <li> EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_CMD_TYPE = AT_CMD_TYPE_SET </li>
+     *   <li> EXTRA_VENDOR_SPECIFIC_HEADSET_EVENT_ARGS = foo, 3 <li>
+     * </ul>
+     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission
+     * to receive.
      */
     @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION)
     public static final String ACTION_VENDOR_SPECIFIC_HEADSET_EVENT =
@@ -184,7 +192,7 @@ public final class BluetoothHeadset implements BluetoothProfile {
             "android.bluetooth.headset.intent.category.companyid";
 
     /**
-     * Headset state when SCO audio is not connected
+     * Headset state when SCO audio is not connected.
      * This state can be one of
      * {@link #EXTRA_STATE} or {@link #EXTRA_PREVIOUS_STATE} of
      * {@link #ACTION_AUDIO_STATE_CHANGED} intent.
@@ -192,7 +200,7 @@ public final class BluetoothHeadset implements BluetoothProfile {
     public static final int STATE_AUDIO_DISCONNECTED = 10;
 
     /**
-     * Headset state when SCO audio is connecting
+     * Headset state when SCO audio is connecting.
      * This state can be one of
      * {@link #EXTRA_STATE} or {@link #EXTRA_PREVIOUS_STATE} of
      * {@link #ACTION_AUDIO_STATE_CHANGED} intent.
@@ -200,7 +208,7 @@ public final class BluetoothHeadset implements BluetoothProfile {
     public static final int STATE_AUDIO_CONNECTING = 11;
 
     /**
-     * Headset state when SCO audio is connected
+     * Headset state when SCO audio is connected.
      * This state can be one of
      * {@link #EXTRA_STATE} or {@link #EXTRA_PREVIOUS_STATE} of
      * {@link #ACTION_AUDIO_STATE_CHANGED} intent.
@@ -410,7 +418,7 @@ public final class BluetoothHeadset implements BluetoothProfile {
      * Stop Bluetooth Voice Recognition mode, and shut down the
      * Bluetooth audio path.
      *
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH}
+     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.
      *
      * @param device Bluetooth headset
      * @return false if there is no headset connected
@@ -433,7 +441,7 @@ public final class BluetoothHeadset implements BluetoothProfile {
     /**
      * Check if Bluetooth SCO audio is connected.
      *
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH}
+     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.
      *
      * @param device Bluetooth headset
      * @return true if SCO is connected,
diff --git a/core/java/android/bluetooth/BluetoothProfile.java b/core/java/android/bluetooth/BluetoothProfile.java
index 3949b26186ebd..ef80195d935d4 100644
--- a/core/java/android/bluetooth/BluetoothProfile.java
+++ b/core/java/android/bluetooth/BluetoothProfile.java
@@ -105,6 +105,7 @@ public interface BluetoothProfile {
      * from this intent.
      *
      * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}
+     * permission.
      *
      * @param device Remote Bluetooth Device
      * @return false on immediate error,
@@ -132,6 +133,7 @@ public interface BluetoothProfile {
      * two scenarios.
      *
      * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}
+     * permission.
      *
      * @param device Remote Bluetooth Device
      * @return false on immediate error,
@@ -145,20 +147,20 @@ public interface BluetoothProfile {
      *
      * <p> Return the set of devices which are in state {@link #STATE_CONNECTED}
      *
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH}
+     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.
      *
      * @return List of devices. The list will be empty on error.
      */
     public List<BluetoothDevice> getConnectedDevices();
 
     /**
-     * Get a set of devices that match any of the given connection
+     * Get a list of devices that match any of the given connection
      * states.
      *
-     * <p> If none of devices match any of the given states,
-     * an empty set will be returned.
+     * <p> If none of the devices match any of the given states,
+     * an empty list will be returned.
      *
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH}
+     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.
      *
      * @param states Array of states. States can be one of
      *              {@link #STATE_CONNECTED}, {@link #STATE_CONNECTING},
@@ -170,7 +172,7 @@ public interface BluetoothProfile {
     /**
      * Get the current connection state of the profile
      *
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH}
+     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.
      *
      * @param device Remote bluetooth device.
      * @return State of the profile connection. One of
@@ -187,6 +189,7 @@ public interface BluetoothProfile {
      * {@link #PRIORITY_OFF},
      *
      * <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}
+     * permission.
      *
      * @param device Paired bluetooth device
      * @param priority
@@ -202,7 +205,7 @@ public interface BluetoothProfile {
      * {@link #PRIORITY_AUTO_CONNECT}, {@link #PRIORITY_OFF},
      * {@link #PRIORITY_ON}, {@link #PRIORITY_UNDEFINED}
      *
-     * <p>Requires {@link android.Manifest.permission#BLUETOOTH}
+     * <p>Requires {@link android.Manifest.permission#BLUETOOTH} permission.
      *
      * @param device Bluetooth device
      * @return priority of the device