docs: mix of BT and NFC javadoc updates
Add Health profile to various discussions about profiles
Add descriptions to NFC interfaces, tweak some desciptions, and fix some broken links
Change-Id: Ib89434c78a4ad60b4358dca9a6c335451d1c4125
diff --git a/core/java/android/bluetooth/BluetoothAdapter.java b/core/java/android/bluetooth/BluetoothAdapter.java
index 254c98f..ea5c3db 100644
--- a/core/java/android/bluetooth/BluetoothAdapter.java
+++ b/core/java/android/bluetooth/BluetoothAdapter.java
@@ -781,7 +781,7 @@
* Get the current connection state of a profile.
* This function can be used to check whether the local Bluetooth adapter
* is connected to any remote device for a specific profile.
- * Profile can be one of {@link BluetoothProfile#HEADSET},
+ * Profile can be one of {@link BluetoothProfile#HEALTH}, {@link BluetoothProfile#HEADSET},
* {@link BluetoothProfile#A2DP}.
*
* <p>Requires {@link android.Manifest.permission#BLUETOOTH}.
@@ -1132,15 +1132,15 @@
/**
* Get the profile proxy object associated with the profile.
*
- * <p>Profile can be one of {@link BluetoothProfile#HEADSET} or
+ * <p>Profile can be one of {@link BluetoothProfile#HEALTH}, {@link BluetoothProfile#HEADSET} or
* {@link BluetoothProfile#A2DP}. Clients must implements
* {@link BluetoothProfile.ServiceListener} to get notified of
* the connection status and to get the proxy object.
*
* @param context Context of the application
* @param listener The service Listener for connection callbacks.
- * @param profile The Bluetooth profile; either {@link BluetoothProfile#HEADSET}
- * or {@link BluetoothProfile#A2DP}.
+ * @param profile The Bluetooth profile; either {@link BluetoothProfile#HEALTH},
+ * {@link BluetoothProfile#HEADSET} or {@link BluetoothProfile#A2DP}.
* @return true on success, false on error
*/
public boolean getProfileProxy(Context context, BluetoothProfile.ServiceListener listener,
@@ -1172,7 +1172,7 @@
*
* <p> Clients should call this when they are no longer using
* the proxy obtained from {@link #getProfileProxy}.
- * Profile can be one of {@link BluetoothProfile#HEADSET} or
+ * Profile can be one of {@link BluetoothProfile#HEALTH}, {@link BluetoothProfile#HEADSET} or
* {@link BluetoothProfile#A2DP}
*
* @param profile
diff --git a/core/java/android/bluetooth/BluetoothProfile.java b/core/java/android/bluetooth/BluetoothProfile.java
index f7ccfbd..1920efa 100644
--- a/core/java/android/bluetooth/BluetoothProfile.java
+++ b/core/java/android/bluetooth/BluetoothProfile.java
@@ -161,9 +161,9 @@
/**
* Called to notify the client when the proxy object has been
* connected to the service.
- * @param profile - One of {@link #HEADSET} or
+ * @param profile - One of {@link #HEALTH}, {@link #HEADSET} or
* {@link #A2DP}
- * @param proxy - One of {@link BluetoothHeadset} or
+ * @param proxy - One of {@link BluetoothHealth}, {@link BluetoothHeadset} or
* {@link BluetoothA2dp}
*/
public void onServiceConnected(int profile, BluetoothProfile proxy);
@@ -171,7 +171,7 @@
/**
* Called to notify the client that this proxy object has been
* disconnected from the service.
- * @param profile - One of {@link #HEADSET} or
+ * @param profile - One of {@link #HEALTH}, {@link #HEADSET} or
* {@link #A2DP}
*/
public void onServiceDisconnected(int profile);
diff --git a/core/java/android/nfc/NfcAdapter.java b/core/java/android/nfc/NfcAdapter.java
index e392bca..fe0106d 100644
--- a/core/java/android/nfc/NfcAdapter.java
+++ b/core/java/android/nfc/NfcAdapter.java
@@ -208,7 +208,9 @@
final NfcActivityManager mNfcActivityManager;
/**
- * @see {@link #setNdefPushMessageCallback}
+ * A callback to be invoked when the system successfully delivers your {@link NdefMessage}
+ * to another device.
+ * @see #setOnNdefPushCompleteCallback
*/
public interface OnNdefPushCompleteCallback {
/**
@@ -217,13 +219,21 @@
* <p>This callback is usually made on a binder thread (not the UI thread).
*
* @param event {@link NfcEvent} with the {@link NfcEvent#nfcAdapter} field set
- * @see {@link #setNdefPushMessageCallback}
+ * @see #setNdefPushMessageCallback
*/
public void onNdefPushComplete(NfcEvent event);
}
/**
- * @see {@link #setCeateNdefMessageCallback}
+ * A callback to be invoked when another NFC device capable of NDEF push (Android Beam)
+ * is within range.
+ * <p>Implement this interface and pass it to {@link
+ * NfcAdapter#setNdefPushMessageCallback setNdefPushMessageCallback()} in order to create an
+ * {@link NdefMessage} at the moment that another device is within range for NFC. Using this
+ * callback allows you to create a message with data that might vary based on the
+ * content currently visible to the user. Alternatively, you can call {@link
+ * #setNdefPushMessage setNdefPushMessage()} if the {@link NdefMessage} always contains the
+ * same data.
*/
public interface CreateNdefMessageCallback {
/**
@@ -507,13 +517,15 @@
* <p>Pass a null NDEF message to disable foreground NDEF push in the
* specified activities.
*
- * <p>One or more activities must be specified.
+ * <p>At least one activity must be specified, and usually only one is necessary.
*
* <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
*
* @param message NDEF message to push over NFC, or null to disable
- * @param activity an activity to enable for NDEF push (at least one is required)
- * @param activities zero or more additional activities to enable for NDEF Push
+ * @param activity an activity in which NDEF push should be enabled to share the provided
+ * NDEF message
+ * @param activities optional additional activities that should also enable NDEF push with
+ * the provided NDEF message
*/
public void setNdefPushMessage(NdefMessage message, Activity activity,
Activity ... activities) {
@@ -544,13 +556,15 @@
* <p>Pass a null callback to disable the callback in the
* specified activities.
*
- * <p>One or more activities must be specified.
+ * <p>At least one activity must be specified, and usually only one is necessary.
*
* <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
*
* @param callback callback, or null to disable
- * @param activity an activity to enable for NDEF push (at least one is required)
- * @param activities zero or more additional activities to enable for NDEF Push
+ * @param activity an activity in which NDEF push should be enabled to share an NDEF message
+ * that's retrieved from the provided callback
+ * @param activities optional additional activities that should also enable NDEF push using
+ * the provided callback
*/
public void setNdefPushMessageCallback(CreateNdefMessageCallback callback, Activity activity,
Activity ... activities) {
diff --git a/core/java/android/nfc/NfcEvent.java b/core/java/android/nfc/NfcEvent.java
index b00d8b7..860700a 100644
--- a/core/java/android/nfc/NfcEvent.java
+++ b/core/java/android/nfc/NfcEvent.java
@@ -29,8 +29,8 @@
* in the callback) because it allows new fields to be added without breaking
* API compatibility.
*
- * @see {@link NfcAdapter.OnNdefPushCompleteCallback#onNdefPushComplete}
- * @see {@link NfcAdapter.CreateNdefMessageCallback#createNdefMessage}
+ * @see NfcAdapter.OnNdefPushCompleteCallback#onNdefPushComplete
+ * @see NfcAdapter.CreateNdefMessageCallback#createNdefMessage
*/
public final class NfcEvent {
/**