docs: mix of BT and NFC javadoc updates

scottamain · scottamain · commit 2d68a6ba3c13 · 2011-09-27T14:04:48.000-07:00
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
@@ -781,7 +781,7 @@ public int getConnectionState() {
      * 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 @@ public Pair<byte[], byte[]> readOutOfBandData() {
     /**
      * 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 @@ public boolean getProfileProxy(Context context, BluetoothProfile.ServiceListener
      *
      * <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
@@ -161,17 +161,17 @@ public interface ServiceListener {
         /**
          * 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);
 
         /**
          * 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
@@ -208,7 +208,9 @@ public final class NfcAdapter {
     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 @@ public interface OnNdefPushCompleteCallback {
          * <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 @@ public boolean disable() {
      * <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 @@ public void setNdefPushMessage(NdefMessage message, Activity activity,
      * <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
@@ -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 {
     /**
