Revise some javadocs for NFC; add package description

Change-Id: I60223e2ad24af98b3b16a74960365185096ae614

8 files changed, 104 insertions, 68 deletions

diff --git a/core/java/android/nfc/NdefMessage.java b/core/java/android/nfc/NdefMessage.java
index fcff2c9..378304e 100644
--- a/core/java/android/nfc/NdefMessage.java
+++ b/core/java/android/nfc/NdefMessage.java
@@ -21,10 +21,12 @@ import android.os.Parcel;
 import android.os.Parcelable;
 
 /**
- * NDEF Message data.
- * <p>
- * Immutable data class. An NDEF message always contains zero or more NDEF
- * records.
+ * Represents an NDEF (NFC Data Exchange Format) data message that contains one or more {@link
+ * NdefRecord}s.
+ * <p>An NDEF message includes "records" that can contain different sets of data, such as
+ * MIME-type media, a URI, or one of the supported RTD types (see {@link NdefRecord}). An NDEF
+ * message always contains zero or more NDEF records.</p>
+ * <p>This is an immutable data class.
  */
 public class NdefMessage implements Parcelable {
     private static final byte FLAG_MB = (byte) 0x80;
diff --git a/core/java/android/nfc/NdefRecord.java b/core/java/android/nfc/NdefRecord.java
index c08f2ed..c65dd66 100644
--- a/core/java/android/nfc/NdefRecord.java
+++ b/core/java/android/nfc/NdefRecord.java
@@ -22,20 +22,18 @@ import android.os.Parcelable;
 import java.lang.UnsupportedOperationException;
 
 /**
- * NDEF Record data.
- * <p>
- * Immutable data class. An NDEF record always contains
+ * Represents a logical (unchunked) NDEF (NFC Data Exchange Format) record.
+ * <p>An NDEF record always contains:
  * <ul>
- * <li>3-bit TNF field
- * <li>Variable length type
- * <li>Variable length ID
- * <li>Variable length payload
+ * <li>3-bit TNF (Type Name Format) field: Indicates how to interpret the type field
+ * <li>Variable length type: Describes the record format
+ * <li>Variable length ID: A unique identifier for the record
+ * <li>Variable length payload: The actual data payload
  * </ul>
- * The TNF (Type Name Format) field indicates how to interpret the type field.
- * <p>
- * This class represents a logical (unchunked) NDEF record. The underlying
+ * <p>The underlying record
  * representation may be chunked across several NDEF records when the payload is
  * large.
+ * <p>This is an immutable data class.
  */
 public class NdefRecord implements Parcelable {
     /**
diff --git a/core/java/android/nfc/NdefTag.java b/core/java/android/nfc/NdefTag.java
index 25303c3..6d44e6e 100644
--- a/core/java/android/nfc/NdefTag.java
+++ b/core/java/android/nfc/NdefTag.java
@@ -20,20 +20,18 @@ import android.os.Parcel;
 import android.os.Parcelable;
 
 /**
- * NdefTag is a Tag that has NDEF messages or can store NDEF messages.
+ * Represents a discovered tag that contains {@link NdefMessage}s (or a tag that can store them).
+ * In practice, a tag is a thing that an NFC-enabled device can communicate with. This
+ * class is a representation of such a tag and can contain the NDEF messages shared by the tag.
+ * <p>An NDEF tag can contain zero or more NDEF messages (represented by {@link NdefMessage}
+ * objects) in addition to the basic tag properties of UID and Type.
  * <p>
- * NDEF Tag's contain zero or more NDEF Messages in addition to the basic
- * Tag properties of UID and Type.
- * <p>
- * NDEF Tag's that have been initialized will usually contain a single NDEF
- * Message (and that Message can contain multiple NDEF Records). However it
- * is possible for NDEF Tag's to contain multiple NDEF Messages.
- * <p>
- * This class is a immutable data class that contains the contents of the NDEF
- * Message(s) as read at Tag discovery time.
- * <p>
- * NfcAdapter.createNdefTagConnection() can be used to modify the contents of
- * some NDEF Tag's.
+ * {@link NdefTag}s that have been initialized will usually contain a single {@link NdefMessage}
+ * (and that Message can contain multiple {@link NdefRecord}s). However it
+ * is possible for {@link NdefTag}s to contain multiple {@link NdefMessage}s.
+ * <p>{@link NfcAdapter#createNdefTagConnection createNdefTagConnection()} can be used to modify the
+ * contents of some tags.
+ * <p>This is an immutable data class.
  */
 public class NdefTag extends Tag implements Parcelable {
     private final NdefMessage[] mMessages;
diff --git a/core/java/android/nfc/NdefTagConnection.java b/core/java/android/nfc/NdefTagConnection.java
index 0696b37..8038d1a 100644
--- a/core/java/android/nfc/NdefTagConnection.java
+++ b/core/java/android/nfc/NdefTagConnection.java
@@ -22,7 +22,9 @@ import android.os.RemoteException;
 import android.util.Log;
 
 /**
- * NdefTagConnection is a connection to an NDEF target on an NDEF tag.
+ * A connection to an NDEF target on an {@link NdefTag}.
+ * <p>You can acquire this kind of connection with {@link NfcAdapter#createNdefTagConnection
+ * createNdefTagConnection()}. Use the connection to read or write {@link NdefMessage}s.
  */
 public class NdefTagConnection extends RawTagConnection {
     public static final int NDEF_MODE_READ_ONCE = 1;
@@ -44,7 +46,7 @@ public class NdefTagConnection extends RawTagConnection {
     /**
      * Read NDEF message(s).
      * This will always return the most up to date payload, and can block.
-     * It can be canceled with close().
+     * It can be canceled with {@link RawTagConnection#close}.
      * Most NDEF tags will contain just one NDEF message.
      * <p>
      * @throws FormatException if the tag is not NDEF formatted
@@ -79,12 +81,12 @@ public class NdefTagConnection extends RawTagConnection {
     /**
      * Attempt to write an NDEF message to a tag.
      * This method will block until the data is written. It can be canceled
-     * with close().
+     * with {@link RawTagConnection#close}.
      * Many tags are write-once, so use this method carefully.
      * Specification allows for multiple NDEF messages per NDEF tag, but it is
      * encourage to only write one message, this so API only takes a single
-     * message. Use NdefRecord to write several records to a single tag.
-     * For write-many tags, use makeReadOnly() after this method to attempt
+     * message. Use {@link NdefRecord} to write several records to a single tag.
+     * For write-many tags, use {@link #makeReadOnly} after this method to attempt
      * to prevent further modification. For write-once tags this is not
      * neccesary.
      * Requires NFC_WRITE permission.
@@ -114,7 +116,7 @@ public class NdefTagConnection extends RawTagConnection {
     /**
      * Attempts to make the NDEF data in this tag read-only.
      * This method will block until the action is complete. It can be canceled
-     * with close().
+     * with {@link RawTagConnection#close}.
      * Requires NFC_WRITE permission.
      * @return true if the tag is now read-only
      * @throws IOException if the target is lost, or connection closed
diff --git a/core/java/android/nfc/NfcAdapter.java b/core/java/android/nfc/NfcAdapter.java
index b916b34..37243f7 100644
--- a/core/java/android/nfc/NfcAdapter.java
+++ b/core/java/android/nfc/NfcAdapter.java
@@ -24,7 +24,7 @@ import android.util.Log;
 
 //TODO(npelly) permission {@link android.Manifest.permission#NFC_MODIFY}
 /**
- * Represents a local NFC Adapter.
+ * Represents the device's local NFC adapter.
  * <p>
  * Use the static {@link #getDefaultAdapter} method to get the default NFC
  * Adapter for this Android device. Most Android devices will have only one NFC
diff --git a/core/java/android/nfc/RawTagConnection.java b/core/java/android/nfc/RawTagConnection.java
index 67a836f..50e2a5d 100644
--- a/core/java/android/nfc/RawTagConnection.java
+++ b/core/java/android/nfc/RawTagConnection.java
@@ -22,18 +22,16 @@ import android.os.RemoteException;
 import android.util.Log;
 
 /**
- * RawTagConnection is a low-level connection to a Tag.
+ * A low-level connection to a {@link Tag} target.
+ * <p>You can acquire this kind of connection with {@link NfcAdapter#createRawTagConnection
+ * createRawTagConnection()}. Use the connection to send and receive data with {@link #transceive
+ * transceive()}.
  * <p>
- * The only data transfer method that TagConnection offers is transceive().
- * Applications must implement there own protocol stack on top of transceive().
- * <p>
- * Use NfcAdapter.createRawTagConnection() to create a RawTagConnection object.
+ * Applications must implement their own protocol stack on top of {@link #transceive transceive()}.
  *
- * * <p class="note"><strong>Note:</strong>
- * Most methods require the {@link android.Manifest.permission#BLUETOOTH}
- * permission and some also require the
- * {@link android.Manifest.permission#BLUETOOTH_ADMIN} permission.
-
+ * <p class="note"><strong>Note:</strong>
+ * Most methods require the TODO
+ * permission.
  */
 public class RawTagConnection {
 
@@ -52,7 +50,7 @@ public class RawTagConnection {
     }
 
     /**
-     * Get the Tag this connection is associated with.
+     * Get the {@link Tag} this connection is associated with.
      */
     public Tag getTag() {
         return mTag;
@@ -64,13 +62,14 @@ public class RawTagConnection {
     }
 
     /**
-     * Helper to indicate if transceive() calls might succeed.
+     * Helper to indicate if {@link #transceive transceive()} calls might succeed.
      * <p>
      * Does not cause RF activity, and does not block.
      * <p>
-     * Returns true if connect() has completed successfully, and the Tag is not
-     * yet known to be out of range. Applications must still handle IOException
-     * while using transceive().
+     * @return true if {@link #connect} has completed successfully and the {@link Tag} is believed
+     * to be within range. Applications must still handle {@link java.io.IOException}
+     * while using {@link #transceive transceive()}, in case connection is lost after this method
+     * returns true.
      */
     public boolean isConnected() {
         // TODO(nxp): update mIsConnected when tag goes out of range -
@@ -80,11 +79,11 @@ public class RawTagConnection {
     }
 
     /**
-     * Connect to tag.
+     * Connect to the {@link Tag} associated with this connection.
      * <p>
      * This method blocks until the connection is established.
      * <p>
-     * close() can be called from another thread to cancel this connection
+     * {@link #close} can be called from another thread to cancel this connection
      * attempt.
      *
      * @throws IOException if the target is lost, or connect canceled
@@ -95,13 +94,13 @@ public class RawTagConnection {
     }
 
     /**
-     * Close tag connection.
+     * Close this connection.
      * <p>
-     * Causes blocking operations such as transceive() or connect() to
-     * be canceled and immediately throw IOException.
+     * Causes blocking operations such as {@link #transceive transceive()} or {@link #connect} to
+     * be canceled and immediately throw {@link java.io.IOException}.
      * <p>
-     * This object cannot be re-used after calling close(). Further calls
-     * to transceive() or connect() will fail.
+     * Once this method is called, this object cannot be re-used and should be discarded. Further
+     * calls to {@link #transceive transceive()} or {@link #connect} will fail.
      */
     public void close() {
         mIsConnected = false;
@@ -113,10 +112,10 @@ public class RawTagConnection {
     }
 
     /**
-     * Send data to a tag, and return the response.
+     * Send data to a tag and receive the response.
      * <p>
      * This method will block until the response is received. It can be canceled
-     * with close().
+     * with {@link #close}.
      * <p>
      * Requires NFC_WRITE permission.
      *
diff --git a/core/java/android/nfc/Tag.java b/core/java/android/nfc/Tag.java
index 8f731e7..ea21790 100644
--- a/core/java/android/nfc/Tag.java
+++ b/core/java/android/nfc/Tag.java
@@ -20,23 +20,24 @@ import android.os.Parcel;
 import android.os.Parcelable;
 
 /**
- * Immutable data class, represents a discovered tag.
+ * Represents a (generic) discovered tag.
  * <p>
  * A tag is a passive NFC element, such as NFC Forum Tag's, Mifare class Tags,
  * Sony Felica Tags.
  * <p>
  * Tag's have a type and usually have a UID.
  * <p>
- * Tag objects are passed to applications via the NfcAdapter.EXTRA_TAG extra
- * in NfcAdapter.ACTION_TAG_DISCOVERED intents. The Tag object is immutable
- * and represents the state of the Tag at the time of discovery. It can be
- * directly queried for its UID and Type, or used to create a TagConnection
- * (NfcAdapter.createTagConnection()).
+ * {@link Tag} objects are passed to applications via the {@link NfcAdapter#EXTRA_TAG} extra
+ * in {@link NfcAdapter#ACTION_TAG_DISCOVERED} intents. A {@link Tag} object is immutable
+ * and represents the state of the tag at the time of discovery. It can be
+ * directly queried for its UID and Type, or used to create a {@link RawTagConnection}
+ * (with {@link NfcAdapter#createRawTagConnection createRawTagConnection()}).
  * <p>
- * This Tag object can only be used to create a TagConnection while it is in
- * range. If it is removed and then returned to range then the most recent
- * Tag object (in ACTION_TAG_DISCOVERED) should be used to create a
- * TagConnection.
+ * A {@link Tag} can  be used to create a {@link RawTagConnection} only while the tag is in
+ * range. If it is removed and then returned to range, then the most recent
+ * {@link Tag} object (in {@link NfcAdapter#ACTION_TAG_DISCOVERED}) should be used to create a
+ * {@link RawTagConnection}.
+ * <p>This is an immutable data class.
  */
 public class Tag implements Parcelable {
 
diff --git a/core/java/android/nfc/package.html b/core/java/android/nfc/package.html
new file mode 100644
index 0000000..8754cb9
--- /dev/null
+++ b/core/java/android/nfc/package.html
@@ -0,0 +1,36 @@
+<HTML>
+<BODY>
+Provides access to Near Field Communication (NFC) functionality, allowing applications to connect
+to NFC tags, then transmit and recieving data. A "tag" may actually be another device that appears
+as a tag.
+
+<p>Here's a summary of the classes:</p>
+
+<dl>
+  <dt>{@link android.nfc.NfcAdapter}</dt>
+  <dd>This represents the device's NFC adapter, which is your entry-point to performing NFC
+operations. Once you acquire an instance with {@link android.nfc.NfcAdapter#getDefaultAdapter}, you
+can create connections to tags.</dd>
+  <dt>{@link android.nfc.NdefTag} and {@link android.nfc.Tag}</dt>
+  <dd>These objects represent a tag. A tag is a thing that the NFC-enabled device can
+communicate with when within range. Usually, you'll work with {@link android.nfc.NdefTag}, which
+represents a tag that's compliant with the NFC Data Exchange Format (NDEF); a {@link
+android.nfc.Tag} represents a generalized tag. Note that {@link android.nfc.NdefTag} extends
+{@link android.nfc.Tag}.</dd>
+  <dt>{@link android.nfc.NdefTagConnection} and {@link android.nfc.RawTagConnection}</dt>
+  <dd>These objects represent a connection to a tag, respective to the type of tag connected
+(either {@link android.nfc.NdefTag} or {@link android.nfc.Tag}). Note that {@link
+android.nfc.NdefTagConnection} extends {@link android.nfc.RawTagConnection}.</dd>
+  <dt>{@link android.nfc.NdefMessage}</dt>
+  <dd>Represents an NDEF data message, which is the standard format in which "records"
+carrying data are transmitted between devices and tags. Your application can receive these
+messages from an {@link android.nfc.NdefTagConnection}.</dd>
+  <dt>{@link android.nfc.NdefRecord}</dt>
+  <dd>Represents a record, which is delivered in a {@link android.nfc.NdefMessage} and describes the
+type of data being shared and carries the data itself.</dd>
+</dl>
+
+<p class="note"><strong>Note:</strong>
+Not all Android-powered devices provide NFC functionality.</p>
+</BODY>
+</HTML>