Minor documentation improvements.
Based on user-submitted bugs that were just misunderstandings, plus
implementation bugs caused by the intended behavior being somewhat
subtle.
Change-Id: Ic2606b5e57dadc95a35c2d0a977c01434a2fa28a
diff --git a/libcore/luni/src/main/java/java/lang/Double.java b/libcore/luni/src/main/java/java/lang/Double.java
index d6ad58e..95c7b81 100644
--- a/libcore/luni/src/main/java/java/lang/Double.java
+++ b/libcore/luni/src/main/java/java/lang/Double.java
@@ -174,11 +174,13 @@
}
/**
- * 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/libcore/luni/src/main/java/java/lang/Float.java b/libcore/luni/src/main/java/java/lang/Float.java
index 92b1731..54cc246 100644
--- a/libcore/luni/src/main/java/java/lang/Float.java
+++ b/libcore/luni/src/main/java/java/lang/Float.java
@@ -144,10 +144,13 @@
}
/**
- * 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/libcore/luni/src/main/java/java/lang/Integer.java b/libcore/luni/src/main/java/java/lang/Integer.java
index 34b9c16..63cd615 100644
--- a/libcore/luni/src/main/java/java/lang/Integer.java
+++ b/libcore/luni/src/main/java/java/lang/Integer.java
@@ -610,15 +610,20 @@
}
/**
- * 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/libcore/luni/src/main/java/java/lang/Iterable.java b/libcore/luni/src/main/java/java/lang/Iterable.java
index 31883fb..193fb7b 100644
--- a/libcore/luni/src/main/java/java/lang/Iterable.java
+++ b/libcore/luni/src/main/java/java/lang/Iterable.java
@@ -19,8 +19,8 @@
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/libcore/luni/src/main/java/java/lang/Long.java b/libcore/luni/src/main/java/java/lang/Long.java
index 1c52896..2cc4cd7 100644
--- a/libcore/luni/src/main/java/java/lang/Long.java
+++ b/libcore/luni/src/main/java/java/lang/Long.java
@@ -583,15 +583,20 @@
}
/**
- * 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/libcore/luni/src/main/java/java/lang/String.java b/libcore/luni/src/main/java/java/lang/String.java
index 1556389..8e4c9a8 100644
--- a/libcore/luni/src/main/java/java/lang/String.java
+++ b/libcore/luni/src/main/java/java/lang/String.java
@@ -2192,8 +2192,16 @@
}
/**
- * 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/libcore/luni/src/main/java/java/lang/StringBuffer.java b/libcore/luni/src/main/java/java/lang/StringBuffer.java
index 3ec43dc..766b942 100644
--- a/libcore/luni/src/main/java/java/lang/StringBuffer.java
+++ b/libcore/luni/src/main/java/java/lang/StringBuffer.java
@@ -24,21 +24,22 @@
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/libcore/luni/src/main/java/java/lang/StringBuilder.java b/libcore/luni/src/main/java/java/lang/StringBuilder.java
index 12d401f..775864e 100644
--- a/libcore/luni/src/main/java/java/lang/StringBuilder.java
+++ b/libcore/luni/src/main/java/java/lang/StringBuilder.java
@@ -24,20 +24,21 @@
/**
* 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/libcore/luni/src/main/java/java/util/ArrayList.java b/libcore/luni/src/main/java/java/util/ArrayList.java
index 7c46e89..ba96593 100644
--- a/libcore/luni/src/main/java/java/util/ArrayList.java
+++ b/libcore/luni/src/main/java/java/util/ArrayList.java
@@ -29,10 +29,18 @@
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/libcore/luni/src/main/java/java/util/Enumeration.java b/libcore/luni/src/main/java/java/util/Enumeration.java
index 8b8f7bd..5944a75 100644
--- a/libcore/luni/src/main/java/java/util/Enumeration.java
+++ b/libcore/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/libcore/luni/src/main/java/java/util/HashMap.java b/libcore/luni/src/main/java/java/util/HashMap.java
index f79601f..19aa2b8 100644
--- a/libcore/luni/src/main/java/java/util/HashMap.java
+++ b/libcore/luni/src/main/java/java/util/HashMap.java
@@ -29,14 +29,31 @@
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 @@
/**
* 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 @@
/*
* 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 @@
/**
* 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 @@
/**
* 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 @@
}
/**
- * 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 @@
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/libcore/luni/src/main/java/java/util/Hashtable.java b/libcore/luni/src/main/java/java/util/Hashtable.java
index ead0db3..af0f4b3 100644
--- a/libcore/luni/src/main/java/java/util/Hashtable.java
+++ b/libcore/luni/src/main/java/java/util/Hashtable.java
@@ -29,22 +29,15 @@
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 @@
/**
* 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 @@
/*
* 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 @@
/**
* 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 @@
/**
* 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/libcore/luni/src/main/java/java/util/Iterator.java b/libcore/luni/src/main/java/java/util/Iterator.java
index 6ebae04..bec797b 100644
--- a/libcore/luni/src/main/java/java/util/Iterator.java
+++ b/libcore/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 @@
/**
* 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/libcore/luni/src/main/java/java/util/LinkedHashMap.java b/libcore/luni/src/main/java/java/util/LinkedHashMap.java
index cd6825b..eeee1a9 100644
--- a/libcore/luni/src/main/java/java/util/LinkedHashMap.java
+++ b/libcore/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/libcore/luni/src/main/java/java/util/LinkedList.java b/libcore/luni/src/main/java/java/util/LinkedList.java
index 7a7e81f..9db9c9c 100644
--- a/libcore/luni/src/main/java/java/util/LinkedList.java
+++ b/libcore/luni/src/main/java/java/util/LinkedList.java
@@ -24,10 +24,16 @@
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/libcore/luni/src/main/java/java/util/Vector.java b/libcore/luni/src/main/java/java/util/Vector.java
index 9a1b81c..8129cfe 100644
--- a/libcore/luni/src/main/java/java/util/Vector.java
+++ b/libcore/luni/src/main/java/java/util/Vector.java
@@ -23,20 +23,18 @@
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/libcore/nio/src/main/java/java/nio/DoubleBuffer.java b/libcore/nio/src/main/java/java/nio/DoubleBuffer.java
index 4e0ab01..3bea69e 100644
--- a/libcore/nio/src/main/java/java/nio/DoubleBuffer.java
+++ b/libcore/nio/src/main/java/java/nio/DoubleBuffer.java
@@ -233,12 +233,17 @@
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 @@
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/libcore/nio/src/main/java/java/nio/FloatBuffer.java b/libcore/nio/src/main/java/java/nio/FloatBuffer.java
index cab94c3..15239b1 100644
--- a/libcore/nio/src/main/java/java/nio/FloatBuffer.java
+++ b/libcore/nio/src/main/java/java/nio/FloatBuffer.java
@@ -233,12 +233,17 @@
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 @@
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/libcore/sql/src/main/java/java/sql/package.html b/libcore/sql/src/main/java/java/sql/package.html
index 9ae2488..0799bb7 100644
--- a/libcore/sql/src/main/java/java/sql/package.html
+++ b/libcore/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>
