Merge "Minor documentation improvements."

19 files changed, 212 insertions, 147 deletions

diff --git a/luni/src/main/java/java/lang/Double.java b/luni/src/main/java/java/lang/Double.java
index d6ad58e..95c7b81 100644
--- a/luni/src/main/java/java/lang/Double.java
+++ b/luni/src/main/java/java/lang/Double.java
@@ -174,11 +174,13 @@ public final class Double extends Number implements Comparable<Double> {
     }
 
     /**
-     * Compares this object with the specified object and indicates if they are
-     * equal. In order to be equal, {@code object} must be an instance of
-     * {@code Double} and the bit pattern of its double value is the same as
-     * this object's.
-     *
+     * Tests this double for equality with {@code object}.
+     * To be equal, {@code object} must be an instance of {@code Double} and
+     * {@code doubleToLongBits} must give the same value for both objects.
+     * 
+     * <p>Note that, unlike {@code ==}, {@code -0.0} and {@code +0.0} compare
+     * unequal, and {@code NaN}s compare equal by this method.
+     * 
      * @param object
      *            the object to compare this double with.
      * @return {@code true} if the specified object is equal to this
diff --git a/luni/src/main/java/java/lang/Float.java b/luni/src/main/java/java/lang/Float.java
index 92b1731..54cc246 100644
--- a/luni/src/main/java/java/lang/Float.java
+++ b/luni/src/main/java/java/lang/Float.java
@@ -144,10 +144,13 @@ public final class Float extends Number implements Comparable<Float> {
     }
 
     /**
-     * Compares this instance with the specified object and indicates if they
-     * are equal. In order to be equal, {@code object} must be an instance of
-     * {@code Float} and have the same float value as this object.
-     *
+     * Tests this double for equality with {@code object}.
+     * To be equal, {@code object} must be an instance of {@code Float} and
+     * {@code floatToIntBits} must give the same value for both objects.
+     * 
+     * <p>Note that, unlike {@code ==}, {@code -0.0} and {@code +0.0} compare
+     * unequal, and {@code NaN}s compare equal by this method.
+     * 
      * @param object
      *            the object to compare this float with.
      * @return {@code true} if the specified object is equal to this
diff --git a/luni/src/main/java/java/lang/Integer.java b/luni/src/main/java/java/lang/Integer.java
index 34b9c16..63cd615 100644
--- a/luni/src/main/java/java/lang/Integer.java
+++ b/luni/src/main/java/java/lang/Integer.java
@@ -610,15 +610,20 @@ public final class Integer extends Number implements Comparable<Integer> {
     }
 
     /**
-     * Converts the specified integer into a string representation based on the
+     * Converts the specified signed integer into a string representation based on the
      * specified radix. The returned string is a concatenation of a minus sign
      * if the number is negative and characters from '0' to '9' and 'a' to 'z',
      * depending on the radix. If {@code radix} is not in the interval defined
      * by {@code Character.MIN_RADIX} and {@code Character.MAX_RADIX} then 10 is
      * used as the base for the conversion.
+     * 
+     * <p>This method treats its argument as signed. If you want to convert an
+     * unsigned value to one of the common non-decimal bases, you may find
+     * {@link #toBinaryString}, {@code #toHexString}, or {@link #toOctalString}
+     * more convenient.
      *
      * @param i
-     *            the integer to convert.
+     *            the signed integer to convert.
      * @param radix
      *            the base to use for the conversion.
      * @return the string representation of {@code i}.
diff --git a/luni/src/main/java/java/lang/Iterable.java b/luni/src/main/java/java/lang/Iterable.java
index 31883fb..193fb7b 100644
--- a/luni/src/main/java/java/lang/Iterable.java
+++ b/luni/src/main/java/java/lang/Iterable.java
@@ -19,8 +19,8 @@ package java.lang;
 import java.util.Iterator;
 
 /**
- * Objects of classes that implement this interface can be used within a
- * {@code foreach} statement.
+ * Instances of classes that implement this interface can be used with
+ * the enhanced for loop.
  *
  * @since 1.5
  */
diff --git a/luni/src/main/java/java/lang/Long.java b/luni/src/main/java/java/lang/Long.java
index 1c52896..2cc4cd7 100644
--- a/luni/src/main/java/java/lang/Long.java
+++ b/luni/src/main/java/java/lang/Long.java
@@ -583,15 +583,20 @@ public final class Long extends Number implements Comparable<Long> {
     }
 
     /**
-     * Converts the specified long value into a string representation based on
+     * Converts the specified signed long value into a string representation based on
      * the specified radix. The returned string is a concatenation of a minus
      * sign if the number is negative and characters from '0' to '9' and 'a' to
      * 'z', depending on the radix. If {@code radix} is not in the interval
      * defined by {@code Character.MIN_RADIX} and {@code Character.MAX_RADIX}
      * then 10 is used as the base for the conversion.
+     * 
+     * <p>This method treats its argument as signed. If you want to convert an
+     * unsigned value to one of the common non-decimal bases, you may find
+     * {@link #toBinaryString}, {@code #toHexString}, or {@link #toOctalString}
+     * more convenient.
      *
      * @param v
-     *            the long to convert.
+     *            the signed long to convert.
      * @param radix
      *            the base to use for the conversion.
      * @return the string representation of {@code v}.
diff --git a/luni/src/main/java/java/lang/String.java b/luni/src/main/java/java/lang/String.java
index 1556389..8e4c9a8 100644
--- a/luni/src/main/java/java/lang/String.java
+++ b/luni/src/main/java/java/lang/String.java
@@ -2192,8 +2192,16 @@ public final class String implements Serializable, Comparable<String>,
     }
 
     /**
-     * Returns a formatted string, using the supplied format and arguments,
-     * using the default locale.
+     * Returns a localized formatted string, using the supplied format and arguments,
+     * using the user's default locale.
+     * 
+     * <p>Note that this method can be dangerous: the user's default locale may
+     * not be the locale you tested in, and this may have unexpected effects on
+     * the output. In particular, floating point numbers may be output with
+     * ',' instead of '.' as the decimal separator if that's what the user's
+     * locale dictates. If you're formatting a string other than for human
+     * consumption, you should use {@link #format(Locale,String,Object...}) and
+     * supply {@code Locale.US}.
      * 
      * @param format
      *            a format string.
diff --git a/luni/src/main/java/java/lang/StringBuffer.java b/luni/src/main/java/java/lang/StringBuffer.java
index 3ec43dc..766b942 100644
--- a/luni/src/main/java/java/lang/StringBuffer.java
+++ b/luni/src/main/java/java/lang/StringBuffer.java
@@ -24,21 +24,22 @@ import java.io.ObjectStreamField;
 import java.io.Serializable;
 
 /**
- * StringBuffer is a variable size contiguous indexable array of characters. The
- * length of the StringBuffer is the number of characters it contains. The
- * capacity of the StringBuffer is the number of characters it can hold.
- * <p>
- * Characters may be inserted at any position up to the length of the
- * StringBuffer, increasing the length of the StringBuffer. Characters at any
- * position in the StringBuffer may be replaced, which does not affect the
- * StringBuffer length.
- * <p>
- * The capacity of a StringBuffer may be specified when the StringBuffer is
- * created. If the capacity of the StringBuffer is exceeded, the capacity is
- * increased.
+ * A modifiable {@link CharSequence sequence of characters} for use in creating
+ * strings, where all accesses are synchronized. This class has mostly been replaced
+ * by {@link StringBuilder} because this synchronization is rarely useful. This
+ * class is mainly used to interact with legacy APIs that expose it.
  * 
- * @see String
+ * <p>For particularly complex string-building needs, consider {@link java.util.Formatter}.
+ * 
+ * <p>The majority of the modification methods on this class return {@code
+ * this} so that method calls can be chained together. For example:
+ * {@code new StringBuffer("a").append("b").append("c").toString()}.
+ * 
+ * @see CharSequence
+ * @see Appendable
  * @see StringBuilder
+ * @see String
+ * @see String.format
  * @since 1.0
  */
 public final class StringBuffer extends AbstractStringBuilder implements
diff --git a/luni/src/main/java/java/lang/StringBuilder.java b/luni/src/main/java/java/lang/StringBuilder.java
index 12d401f..775864e 100644
--- a/luni/src/main/java/java/lang/StringBuilder.java
+++ b/luni/src/main/java/java/lang/StringBuilder.java
@@ -24,20 +24,21 @@ import java.io.Serializable;
 
 /**
  * A modifiable {@link CharSequence sequence of characters} for use in creating
- * and modifying Strings. This class is intended as a direct replacement of
+ * strings. This class is intended as a direct replacement of
  * {@link StringBuffer} for non-concurrent use; unlike {@code StringBuffer} this
- * class is not synchronized for thread safety.
- * <p>
- * The majority of the modification methods on this class return {@code
- * StringBuilder}, so that, like {@code StringBuffer}s, they can be used in
- * chaining method calls together. For example, {@code new StringBuilder("One
- * should ").append("always strive ").append("to achieve Harmony")}.
+ * class is not synchronized.
+ * 
+ * <p>For particularly complex string-building needs, consider {@link java.util.Formatter}.
+ * 
+ * <p>The majority of the modification methods on this class return {@code
+ * this} so that method calls can be chained together. For example:
+ * {@code new StringBuilder("a").append("b").append("c").toString()}.
  * 
  * @see CharSequence
  * @see Appendable
  * @see StringBuffer
  * @see String
- * 
+ * @see String.format
  * @since 1.5
  */
 public final class StringBuilder extends AbstractStringBuilder implements
diff --git a/luni/src/main/java/java/util/ArrayList.java b/luni/src/main/java/java/util/ArrayList.java
index 7c46e89..ba96593 100644
--- a/luni/src/main/java/java/util/ArrayList.java
+++ b/luni/src/main/java/java/util/ArrayList.java
@@ -29,10 +29,18 @@ import java.io.Serializable;
 import java.lang.reflect.Array;
 
 /**
- * ArrayList is an implementation of {@link List}, backed by an array. All
- * optional operations adding, removing, and replacing are supported. The
- * elements can be any objects.
- *
+ * ArrayList is an implementation of {@link List}, backed by an array.
+ * All optional operations including adding, removing, and replacing elements are supported.
+ * 
+ * <p>All elements are permitted, including null.
+ * 
+ * <p>This class is a good choice as your default {@code List} implementation.
+ * {@link Vector} synchronizes all operations, but not necessarily in a way that's
+ * meaningful to your application: synchronizing each call to {@code get}, for example, is not
+ * equivalent to synchronizing the list and iterating over it (which is probably what you intended).
+ * {@link java.util.concurrent.CopyOnWriteArrayList} is intended for the special case of very high
+ * concurrency, frequent traversals, and very rare mutations.
+ * 
  * @param <E> The element type of this list.
  * @since 1.2
  */
diff --git a/luni/src/main/java/java/util/Enumeration.java b/luni/src/main/java/java/util/Enumeration.java
index 8b8f7bd..5944a75 100644
--- a/luni/src/main/java/java/util/Enumeration.java
+++ b/luni/src/main/java/java/util/Enumeration.java
@@ -18,15 +18,19 @@
 package java.util;
 
 /**
- * An Enumeration is used to sequence over a collection of objects.
- * <p>
- * Preferably an {@link Iterator} should be used. {@code Iterator} replaces the
+ * A legacy iteration interface.
+ * 
+ * <p>New code should use {@link Iterator} instead. {@code Iterator} replaces the
  * enumeration interface and adds a way to remove elements from a collection.
- *
- * @see Hashtable
- * @see Properties
- * @see Vector
+ * 
+ * <p>If you <i>have</i> an {@code Enumeration} and want a {@code Collection}, you
+ * can use {@link Collections#list} to get a {@code List}.
+ * 
+ * <p>If you <i>need</i> an {@code Enumeration} for a legacy API and have a
+ * {@code Collection}, you can use {@link Collections#enumeration}.
+ * 
  * @version 1.0
+ * @see Iterator
  */
 public interface Enumeration<E> {
 
diff --git a/luni/src/main/java/java/util/HashMap.java b/luni/src/main/java/java/util/HashMap.java
index f79601f..19aa2b8 100644
--- a/luni/src/main/java/java/util/HashMap.java
+++ b/luni/src/main/java/java/util/HashMap.java
@@ -29,14 +29,31 @@ import java.io.ObjectStreamField;
 import java.io.Serializable;
 
 /**
- * HashMap is an implementation of Map. All optional operations (adding and
- * removing) are supported. Keys and values can be any objects.
- *
+ * HashMap is an implementation of {@link Map}. All optional operations are supported.
+ * 
+ * <p>All elements are permitted as keys or values, including null.
+ * 
+ * <p>Note that the iteration order for HashMap is non-deterministic. If you want
+ * deterministic iteration, use {@link LinkedHashMap}.
+ * 
+ * <p>Note: the implementation of {@code HashMap} is not synchronized.
+ * If one thread of several threads accessing an instance modifies the map
+ * structurally, access to the map needs to be synchronized. A structural
+ * modification is an operation that adds or removes an entry. Changes in
+ * the value of an entry are not structural changes.
+ * 
+ * <p>The {@code Iterator} created by calling the {@code iterator} method
+ * may throw a {@code ConcurrentModificationException} if the map is structurally
+ * changed while an iterator is used to iterate over the elements. Only the
+ * {@code remove} method that is provided by the iterator allows for removal of
+ * elements during iteration. It is not possible to guarantee that this
+ * mechanism works in all cases of unsynchronized concurrent modification. It
+ * should only be used for debugging purposes.
+ * 
  * @param <K> the type of keys maintained by this map
  * @param <V> the type of mapped values
  */
-public class HashMap<K, V> extends AbstractMap<K, V>
-        implements Cloneable, Serializable {
+public class HashMap<K, V> extends AbstractMap<K, V> implements Cloneable, Serializable {
     /**
      * Min capacity (other than zero) for a HashMap. Must be a power of two
      * greater than 1 (and less than 1 << 30).
@@ -60,7 +77,7 @@ public class HashMap<K, V> extends AbstractMap<K, V>
     /**
      * The default load factor. Note that this implementation ignores the
      * load factor, but cannot do away with it entirely because it's
-     * metioned in the API.
+     * mentioned in the API.
      *
      * <p>Note that this constant has no impact on the behavior of the program,
      * but it is emitted as part of the serialized form. The load factor of
@@ -165,7 +182,7 @@ public class HashMap<K, V> extends AbstractMap<K, V>
 
         /*
          * Note that this implementation ignores loadFactor; it always uses
-         * a load facator of 3/4. This simplifies the code and generally
+         * a load factor of 3/4. This simplifies the code and generally
          * improves performance.
          */
     }
@@ -184,7 +201,7 @@ public class HashMap<K, V> extends AbstractMap<K, V>
 
     /**
      * Inserts all of the elements of map into this HashMap in a manner
-     * suitable for use by constructors and pseudocostructors (i.e., clone,
+     * suitable for use by constructors and pseudo-constructors (i.e., clone,
      * readObject). Also used by LinkedHashMap.
      */
     final void constructorPutAll(Map<? extends K, ? extends V> map) {
@@ -239,7 +256,7 @@ public class HashMap<K, V> extends AbstractMap<K, V>
     /**
      * This method is called from the pseudo-constructors (clone and readObject)
      * prior to invoking constructorPut/constructorPutAll, which invoke the
-     * overriden constructorNewEntry method. Normally it is a VERY bad idea to
+     * overridden constructorNewEntry method. Normally it is a VERY bad idea to
      * invoke an overridden method from a pseudo-constructor (Effective Java
      * Item 17). In this cases it is unavoidable, and the init method provides a
      * workaround.
@@ -411,7 +428,7 @@ public class HashMap<K, V> extends AbstractMap<K, V>
     }
 
     /**
-     * Give LinkedHashMap a chance to take action when we modify an exisitng
+     * Give LinkedHashMap a chance to take action when we modify an existing
      * entry.
      *
      * @param e the entry we're about to modify.
@@ -879,7 +896,7 @@ public class HashMap<K, V> extends AbstractMap<K, V>
         return o1 == o2 || (o1 != null && o1.equals(o2));
     }
 
-    // Subclass (LinkedHashMap) overrrides these for correct iteration order
+    // Subclass (LinkedHashMap) overrides these for correct iteration order
     Iterator<K> newKeyIterator() { return new KeyIterator();   }
     Iterator<V> newValueIterator() { return new ValueIterator(); }
     Iterator<Entry<K, V>> newEntryIterator() { return new EntryIterator(); }
diff --git a/luni/src/main/java/java/util/Hashtable.java b/luni/src/main/java/java/util/Hashtable.java
index ead0db3..af0f4b3 100644
--- a/luni/src/main/java/java/util/Hashtable.java
+++ b/luni/src/main/java/java/util/Hashtable.java
@@ -29,22 +29,15 @@ import java.io.ObjectStreamField;
 import java.io.Serializable;
 
 /**
- * Hashtable associates keys with values. Both keys and values cannot be null.
- * The size of the Hashtable is the number of key/value pairs it contains. The
- * capacity is the number of key/value pairs the Hashtable can hold. The load
- * factor is a float value which determines how full the Hashtable gets before
- * expanding the capacity. If the load factor of the Hashtable is exceeded, the
- * capacity is doubled.
- *
+ * Hashtable is a synchronized implementation of {@link Map}. All optional operations are supported.
+ * 
+ * <p>Neither keys nor values can be null. (Use {@code HashMap} or {@code LinkedHashMap} if you
+ * need null keys or values.)
+ * 
  * @param <K> the type of keys maintained by this map
  * @param <V> the type of mapped values
- *
- * @see Enumeration
- * @see java.io.Serializable
- * @see java.lang.Object#equals
- * @see java.lang.Object#hashCode
+ * @see HashMap
  */
-
 public class Hashtable<K, V> extends Dictionary<K, V>
         implements Map<K, V>, Cloneable, Serializable {
     /**
@@ -70,7 +63,7 @@ public class Hashtable<K, V> extends Dictionary<K, V>
     /**
      * The default load factor. Note that this implementation ignores the
      * load factor, but cannot do away with it entirely because it's
-     * metioned in the API.
+     * mentioned in the API.
      *
      * <p>Note that this constant has no impact on the behavior of the program,
      * but it is emitted as part of the serialized form. The load factor of
@@ -166,7 +159,7 @@ public class Hashtable<K, V> extends Dictionary<K, V>
 
         /*
          * Note that this implementation ignores loadFactor; it always uses
-         * a load facator of 3/4. This simplifies the code and generally
+         * a load factor of 3/4. This simplifies the code and generally
          * improves performance.
          */
     }
@@ -185,7 +178,7 @@ public class Hashtable<K, V> extends Dictionary<K, V>
 
     /**
      * Inserts all of the elements of map into this Hashtable in a manner
-     * suitable for use by constructors and pseudocostructors (i.e., clone,
+     * suitable for use by constructors and pseudo-constructors (i.e., clone,
      * readObject).
      */
     private void constructorPutAll(Map<? extends K, ? extends V> map) {
@@ -665,7 +658,7 @@ public class Hashtable<K, V> extends Dictionary<K, V>
     /**
      * Note: technically the methods of this class should synchronize the
      * backing map.  However, this would require them to have a reference
-     * to it, which would cause consiserable bloat.  Moreover, the RI
+     * to it, which would cause considerable bloat.  Moreover, the RI
      * behaves the same way.
      */
     private static class HashtableEntry<K, V> implements Entry<K, V> {
diff --git a/luni/src/main/java/java/util/Iterator.java b/luni/src/main/java/java/util/Iterator.java
index 6ebae04..bec797b 100644
--- a/luni/src/main/java/java/util/Iterator.java
+++ b/luni/src/main/java/java/util/Iterator.java
@@ -18,31 +18,29 @@
 package java.util;
 
 /**
- * An {@code Iterator} is used to sequence over a collection of objects.
- * Conceptually, an iterator is always positioned between two elements of a
- * collection. A fresh iterator is always positioned in front of the first
- * element.
+ * An iterator over a sequence of objects, such as a collection.
  * 
- * If a collection has been changed since its creation, methods {@code next} and
- * {@code hasNext()} may throw a {@code ConcurrentModificationException}.
- * Iterators with this behavior are called fail-fast iterators.
+ * <p>If a collection has been changed since the iterator was created,
+ * methods {@code next} and {@code hasNext()} may throw a {@code ConcurrentModificationException}.
+ * It is not possible to guarantee that this mechanism works in all cases of unsynchronized
+ * concurrent modification. It should only be used for debugging purposes. Iterators with this
+ * behavior are called fail-fast iterators.
+ * 
+ * <p>Implementing {@link Iterable} and returning an {@code Iterator} allows your
+ * class to be used as a collection with the enhanced for loop.
  * 
  * @param <E>
  *            the type of object returned by the iterator.
  */
 public interface Iterator<E> {
     /**
-     * Returns whether there are more elements to iterate, i.e. whether the
-     * iterator is positioned in front of an element.
-     * 
-     * @return {@code true} if there are more elements, {@code false} otherwise.
+     * Returns true if there is at least one more element, false otherwise.
      * @see #next
      */
     public boolean hasNext();
 
     /**
-     * Returns the next object in the iteration, i.e. returns the element in
-     * front of the iterator and advances the iterator by one position.
+     * Returns the next object and advances the iterator.
      * 
      * @return the next object.
      * @throws NoSuchElementException
@@ -53,7 +51,7 @@ public interface Iterator<E> {
 
     /**
      * Removes the last object returned by {@code next} from the collection.
-     * This method can only be called once after {@code next} was called.
+     * This method can only be called once between each call to {@code next}.
      * 
      * @throws UnsupportedOperationException
      *             if removing is not supported by the collection being
diff --git a/luni/src/main/java/java/util/LinkedHashMap.java b/luni/src/main/java/java/util/LinkedHashMap.java
index cd6825b..eeee1a9 100644
--- a/luni/src/main/java/java/util/LinkedHashMap.java
+++ b/luni/src/main/java/java/util/LinkedHashMap.java
@@ -22,28 +22,28 @@
 package java.util;
 
 /**
- * LinkedHashMap is a variant of HashMap. Its entries are kept in a
- * doubly-linked list. The iteration order is, by default, the order in which
- * keys were inserted. Reinserting an already existing key doesn't change the
- * order. A key is existing if a call to {@code containsKey} would return true.
- * <p>
- * If the three argument constructor is used, and {@code order} is specified as
+ * LinkedHashMap is an implementation of {@link Map} that guarantees iteration order.
+ * All optional operations are supported.
+ * 
+ * <p>All elements are permitted as keys or values, including null.
+ * 
+ * <p>Entries are kept in a doubly-linked list. The iteration order is, by default, the
+ * order in which keys were inserted. Reinserting an already-present key doesn't change the
+ * order. If the three argument constructor is used, and {@code accessOrder} is specified as
  * {@code true}, the iteration will be in the order that entries were accessed.
- * The access order gets affected by put(), get(), putAll() operations, but not
- * by operations on the collection views.
- * <p>
- * Null elements are allowed, and all the optional map operations are supported.
- * <p>
- * <b>Note:</b> The implementation of {@code LinkedHashMap} is not synchronized.
+ * The access order is affected by {@code put}, {@code get}, and {@code putAll} operations,
+ * but not by operations on the collection views.
+ * 
+ * <p>Note: the implementation of {@code LinkedHashMap} is not synchronized.
  * If one thread of several threads accessing an instance modifies the map
  * structurally, access to the map needs to be synchronized. For
  * insertion-ordered instances a structural modification is an operation that
  * removes or adds an entry. Access-ordered instances also are structurally
- * modified by put(), get() and putAll() since these methods change the order of
- * the entries. Changes in the value of an entry are not structural changes.
- * <p>
- * The Iterator that can be created by calling the {@code iterator} method
- * throws a {@code ConcurrentModificationException} if the map is structurally
+ * modified by {@code put}, {@code get}, and {@code putAll} since these methods
+ * change the order of the entries. Changes in the value of an entry are not structural changes.
+ * 
+ * <p>The {@code Iterator} created by calling the {@code iterator} method
+ * may throw a {@code ConcurrentModificationException} if the map is structurally
  * changed while an iterator is used to iterate over the elements. Only the
  * {@code remove} method that is provided by the iterator allows for removal of
  * elements during iteration. It is not possible to guarantee that this
diff --git a/luni/src/main/java/java/util/LinkedList.java b/luni/src/main/java/java/util/LinkedList.java
index 7a7e81f..9db9c9c 100644
--- a/luni/src/main/java/java/util/LinkedList.java
+++ b/luni/src/main/java/java/util/LinkedList.java
@@ -24,10 +24,16 @@ import java.io.Serializable;
 import java.lang.reflect.Array;
 
 /**
- * LinkedList is an implementation of List, backed by a linked list. All
- * optional operations (adding, removing and replacing) are supported. The
- * elements can be any objects.
- *
+ * LinkedList is an implementation of {@link List}, backed by a doubly-linked list.
+ * All optional operations including adding, removing, and replacing elements are supported.
+ * 
+ * <p>All elements are permitted, including null.
+ * 
+ * <p>This class is primarily useful if you need queue-like behavior. It may also be useful
+ * as a list if you expect your lists to contain zero or one element, but still require the
+ * ability to scale to slightly larger numbers of elements. In general, though, you should
+ * probably use {@link ArrayList} if you don't need the queue-like behavior.
+ * 
  * @since 1.2
  */
 public class LinkedList<E> extends AbstractSequentialList<E> implements
diff --git a/luni/src/main/java/java/util/Vector.java b/luni/src/main/java/java/util/Vector.java
index 9a1b81c..8129cfe 100644
--- a/luni/src/main/java/java/util/Vector.java
+++ b/luni/src/main/java/java/util/Vector.java
@@ -23,20 +23,18 @@ import java.io.Serializable;
 import java.lang.reflect.Array;
 
 /**
- * Vector is a variable size contiguous indexable array of objects. The size of
- * the vector is the number of objects it contains. The capacity of the vector
- * is the number of objects it can hold.
- * <p>
- * Objects may be inserted at any position up to the size of the vector, thus
- * increasing the size of the vector. Objects at any position in the vector may
- * be removed, thus shrinking the size of the Vector. Objects at any position in
- * the Vector may be replaced, which does not affect the vector's size.
- * <p>
- * The capacity of a vector may be specified when the vector is created. If the
- * capacity of the vector is exceeded, the capacity is increased (doubled by
- * default).
- *
- * @see java.lang.StringBuffer
+ * Vector is an implementation of {@link List}, backed by an array and synchronized.
+ * All optional operations including adding, removing, and replacing elements are supported.
+ * 
+ * <p>All elements are permitted, including null.
+ * 
+ * <p>This class is equivalent to {@link ArrayList} with synchronized operations. This has a
+ * performance cost, and the synchronization is not necessarily meaningful to your application:
+ * synchronizing each call to {@code get}, for example, is not equivalent to synchronizing on the
+ * list and iterating over it (which is probably what you intended). If you do need very highly
+ * concurrent access, you should also consider {@link CopyOnWriteArrayList}.
+ * 
+ * @param <E> The element type of this list.
  */
 public class Vector<E> extends AbstractList<E> implements List<E>,
         RandomAccess, Cloneable, Serializable {
diff --git a/nio/src/main/java/java/nio/DoubleBuffer.java b/nio/src/main/java/java/nio/DoubleBuffer.java
index 4e0ab01..3bea69e 100644
--- a/nio/src/main/java/java/nio/DoubleBuffer.java
+++ b/nio/src/main/java/java/nio/DoubleBuffer.java
@@ -233,12 +233,17 @@ public abstract class DoubleBuffer extends Buffer implements
     public abstract DoubleBuffer duplicate();
 
     /**
-     * Checks whether this double buffer is equal to another object.
-     * <p>
-     * If {@code other} is not a double buffer then {@code false} is returned.
-     * Two double buffers are equal if and only if their remaining doubles are
-     * exactly the same. Position, limit, capacity and mark are not considered.
-     *
+     * Checks whether this double buffer is equal to another object. If {@code
+     * other} is not a {@code DoubleBuffer} then {@code false} is returned.
+     * 
+     * <p>Two double buffers are equal if their remaining doubles are equal.
+     * Position, limit, capacity and mark are not considered.
+     * 
+     * <p>This method considers two doubles {@code a} and {@code b} to be equal
+     * if {@code a == b} or if {@code a} and {@code b} are both {@code NaN}.
+     * Unlike {@link Double#equals}, this method considers {@code -0.0} and
+     * {@code +0.0} to be equal.
+     * 
      * @param other
      *            the object to compare with this double buffer.
      * @return {@code true} if this double buffer is equal to {@code other},
@@ -259,7 +264,9 @@ public abstract class DoubleBuffer extends Buffer implements
         int otherPosition = otherBuffer.position;
         boolean equalSoFar = true;
         while (equalSoFar && (myPosition < limit)) {
-            equalSoFar = get(myPosition++) == otherBuffer.get(otherPosition++);
+            double a = get(myPosition++);
+            double b = otherBuffer.get(otherPosition++);
+            equalSoFar = a == b || (a != a && b != b);
         }
 
         return equalSoFar;
diff --git a/nio/src/main/java/java/nio/FloatBuffer.java b/nio/src/main/java/java/nio/FloatBuffer.java
index cab94c3..15239b1 100644
--- a/nio/src/main/java/java/nio/FloatBuffer.java
+++ b/nio/src/main/java/java/nio/FloatBuffer.java
@@ -233,12 +233,17 @@ public abstract class FloatBuffer extends Buffer implements
     public abstract FloatBuffer duplicate();
 
     /**
-     * Checks whether this float buffer is equal to another object.
-     * <p>
-     * If {@code other} is not a float buffer then {@code false} is returned.
-     * Two float buffers are equal if and only if their remaining floats are
-     * exactly the same. Position, limit, capacity and mark are not considered.
-     *
+     * Checks whether this float buffer is equal to another object. If {@code
+     * other} is not a {@code FloatBuffer} then {@code false} is returned.
+     * 
+     * <p>Two float buffers are equal if their remaining floats are equal.
+     * Position, limit, capacity and mark are not considered.
+     * 
+     * <p>This method considers two floats {@code a} and {@code b} to be equal
+     * if {@code a == b} or if {@code a} and {@code b} are both {@code NaN}.
+     * Unlike {@link Float#equals}, this method considers {@code -0.0} and
+     * {@code +0.0} to be equal.
+     * 
      * @param other
      *            the object to compare with this float buffer.
      * @return {@code true} if this float buffer is equal to {@code other},
@@ -259,7 +264,9 @@ public abstract class FloatBuffer extends Buffer implements
         int otherPosition = otherBuffer.position;
         boolean equalSoFar = true;
         while (equalSoFar && (myPosition < limit)) {
-            equalSoFar = get(myPosition++) == otherBuffer.get(otherPosition++);
+            float a = get(myPosition++);
+            float b = otherBuffer.get(otherPosition++);
+            equalSoFar = a == b || (a != a && b != b);
         }
 
         return equalSoFar;
diff --git a/sql/src/main/java/java/sql/package.html b/sql/src/main/java/java/sql/package.html
index 9ae2488..0799bb7 100644
--- a/sql/src/main/java/java/sql/package.html
+++ b/sql/src/main/java/java/sql/package.html
@@ -1,8 +1,10 @@
 <html>
-  <body>
-    <p>
-      Provides a standard interface for accessing SQL-based databases.
-    </p>
-    @since Android 1.0
-  </body>
-</html>
\ No newline at end of file
+<body>
+<p>Provides a compatibility interface for accessing SQL-based databases.
+The <code>android.database</code> and <code>android.database.sqlite</code>
+packages offer a higher-performance alternative where source compatibility
+is not an issue.</p>
+
+<p>Note that you must provide your own JDBC driver.</p>
+</body>
+</html>