Improve readability of java docs for the public APIs.
Change-Id: I0a0f1be04ed2ea2c14498a1a2ed4b050191ec95b
diff --git a/core/java/android/bluetooth/BluetoothA2dp.java b/core/java/android/bluetooth/BluetoothA2dp.java
index 61b4303..231f592 100644
--- a/core/java/android/bluetooth/BluetoothA2dp.java
+++ b/core/java/android/bluetooth/BluetoothA2dp.java
@@ -50,15 +50,18 @@
* 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 @@
* 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 @@
/**
* 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 @@
*
* <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 24217d7..254e2f8 100644
--- a/core/java/android/bluetooth/BluetoothDevice.java
+++ b/core/java/android/bluetooth/BluetoothDevice.java
@@ -748,6 +748,15 @@
* 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 @@
* 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 a7e4518..f5f6092 100644
--- a/core/java/android/bluetooth/BluetoothHeadset.java
+++ b/core/java/android/bluetooth/BluetoothHeadset.java
@@ -52,15 +52,17 @@
* 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 @@
* 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 @@
* 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 @@
* 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 @@
"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 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 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 @@
* 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 @@
/**
* 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 3949b26..ef80195 100644
--- a/core/java/android/bluetooth/BluetoothProfile.java
+++ b/core/java/android/bluetooth/BluetoothProfile.java
@@ -105,6 +105,7 @@
* 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 @@
* 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 @@
*
* <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 @@
/**
* 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 @@
* {@link #PRIORITY_OFF},
*
* <p>Requires {@link android.Manifest.permission#BLUETOOTH_ADMIN}
+ * permission.
*
* @param device Paired bluetooth device
* @param priority
@@ -202,7 +205,7 @@
* {@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