--- jsr166/src/main/java/util/LinkedList.java	2005/05/14 02:19:00	1.27
+++ jsr166/src/main/java/util/LinkedList.java	2005/05/17 06:36:47	1.30
@@ -165,8 +165,8 @@ public class LinkedList<E>
     /**
      * Returns <tt>true</tt> if this list contains the specified element.
      * More formally, returns <tt>true</tt> if and only if this list contains
-     * at least one element <tt>e</tt> such that <tt>(o==null ? e==null
-     * : o.equals(e))</tt>.
+     * at least one element <tt>e</tt> such that
+     * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.
      *
      * @param o element whose presence in this list is to be tested
      * @return <tt>true</tt> if this list contains the specified element
@@ -196,14 +196,17 @@ public class LinkedList<E>
     }
 
     /**
-     * Removes the first occurrence of the specified element in this list.  If
-     * the list does not contain the element, it is unchanged.  More formally,
-     * removes the element with the lowest index <tt>i</tt> such that
-     * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt> (if such an
-     * element exists).
+     * Removes the first occurrence of the specified element from this list,
+     * if it is present.  If this list does not contain the element, it is
+     * unchanged.  More formally, removes the element with the lowest index
+     * <tt>i</tt> such that
+     * <tt>(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i)))</tt>
+     * (if such an element exists).  Returns <tt>true</tt> if this list
+     * contained the specified element (or equivalently, if this list
+     * changed as a result of the call).
      *
      * @param o element to be removed from this list, if present
-     * @return <tt>true</tt> if the list contained the specified element
+     * @return <tt>true</tt> if this list contained the specified element
      */
     public boolean remove(Object o) {
         if (o==null) {
@@ -252,8 +255,7 @@ public class LinkedList<E>
      *              from the specified collection
      * @param c elements to be inserted into this list
      * @return <tt>true</tt> if this list changed as a result of the call
-     * @throws IndexOutOfBoundsException if the index is out of range
-     *         (<tt>index &lt; 0 || index &gt; size()</tt>)
+     * @throws IndexOutOfBoundsException {@inheritDoc}
      * @throws NullPointerException if the specified collection is null
      */
     public boolean addAll(int index, Collection<? extends E> c) {
@@ -301,10 +303,9 @@ public class LinkedList<E>
     /**
      * Returns the element at the specified position in this list.
      *
-     * @param index index of element to return
+     * @param index index of the element to return
      * @return the element at the specified position in this list
-     * @throws IndexOutOfBoundsException if the index is out of range
-     *         (<tt>index &lt; 0 || index &gt; size()</tt>)
+     * @throws IndexOutOfBoundsException {@inheritDoc}
      */
     public E get(int index) {
         return entry(index).element;
@@ -314,11 +315,10 @@ public class LinkedList<E>
      * Replaces the element at the specified position in this list with the
      * specified element.
      *
-     * @param index index of element to replace
+     * @param index index of the element to replace
      * @param element element to be stored at the specified position
      * @return the element previously at the specified position
-     * @throws IndexOutOfBoundsException if the index is out of range
-     *         (<tt>index &lt; 0 || index &gt; size()</tt>)
+     * @throws IndexOutOfBoundsException {@inheritDoc}
      */
     public E set(int index, E element) {
         Entry<E> e = entry(index);
@@ -334,9 +334,7 @@ public class LinkedList<E>
      *
      * @param index index at which the specified element is to be inserted
      * @param element element to be inserted
-     *
-     * @throws IndexOutOfBoundsException if the index is out of range
-     *         (<tt>index &lt; 0 || index &gt; size()</tt>)
+     * @throws IndexOutOfBoundsException {@inheritDoc}
      */
     public void add(int index, E element) {
         addBefore(element, (index==size ? header : entry(index)));
@@ -349,9 +347,7 @@ public class LinkedList<E>
      *
      * @param index the index of the element to be removed
      * @return the element previously at the specified position
-     *
-     * @throws IndexOutOfBoundsException if the index is out of range
-     *         (<tt>index &lt; 0 || index &gt; size()</tt>)
+     * @throws IndexOutOfBoundsException {@inheritDoc}
      */
     public E remove(int index) {
         return remove(entry(index));
@@ -379,16 +375,15 @@ public class LinkedList<E>
     // Search Operations
 
     /**
-     * Returns the index in this list of the first occurrence of the
-     * specified element, or -1 if the List does not contain this
-     * element.  More formally, returns the lowest index i such that
-     * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>, or -1 if
-     * there is no such index.
+     * Returns the index of the first occurrence of the specified element
+     * in this list, or -1 if this list does not contain the element.
+     * More formally, returns the lowest index <tt>i</tt> such that
+     * <tt>(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i)))</tt>,
+     * or -1 if there is no such index.
      *
      * @param o element to search for
-     * @return the index in this list of the first occurrence of the
-     *         specified element, or -1 if the list does not contain this
-     *         element
+     * @return the index of the first occurrence of the specified element in
+     *         this list, or -1 if this list does not contain the element
      */
     public int indexOf(Object o) {
         int index = 0;
@@ -409,16 +404,15 @@ public class LinkedList<E>
     }
 
     /**
-     * Returns the index in this list of the last occurrence of the
-     * specified element, or -1 if the list does not contain this
-     * element.  More formally, returns the highest index i such that
-     * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>, or -1 if
-     * there is no such index.
+     * Returns the index of the last occurrence of the specified element
+     * in this list, or -1 if this list does not contain the element.
+     * More formally, returns the highest index <tt>i</tt> such that
+     * <tt>(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i)))</tt>,
+     * or -1 if there is no such index.
      *
      * @param o element to search for
-     * @return the index in this list of the last occurrence of the
-     *         specified element, or -1 if the list does not contain this
-     *         element
+     * @return the index of the last occurrence of the specified element in
+     *         this list, or -1 if this list does not contain the element
      */
     public int lastIndexOf(Object o) {
         int index = size;
@@ -524,7 +518,7 @@ public class LinkedList<E>
      * or returns <tt>null</tt> if this list is empty.
      *
      * @return the first element of this list, or <tt>null</tt>
-     *         if this list is empty.
+     *         if this list is empty
      * @since 1.6
      */
     public E peekFirst() {
@@ -538,7 +532,7 @@ public class LinkedList<E>
      * or returns <tt>null</tt> if this list is empty.
      *
      * @return the last element of this list, or <tt>null</tt>
-     *         if this list is empty.
+     *         if this list is empty
      * @since 1.6
      */
     public E peekLast() {
@@ -659,11 +653,10 @@ public class LinkedList<E>
      * time in the future.
      *
      * @param index index of the first element to be returned from the
-     *              list-iterator (by a call to <tt>next</tt>).
+     *              list-iterator (by a call to <tt>next</tt>)
      * @return a ListIterator of the elements in this list (in proper
-     *         sequence), starting at the specified position in the list.
-     * @throws IndexOutOfBoundsException if the index is out of range
-     *         (<tt>index &lt; 0 || index &gt; size()</tt>).
+     *         sequence), starting at the specified position in the list
+     * @throws IndexOutOfBoundsException {@inheritDoc}
      * @see List#listIterator(int)
      */
     public ListIterator<E> listIterator(int index) {
@@ -829,10 +822,17 @@ public class LinkedList<E>
 
     /**
      * Returns an array containing all of the elements in this list
-     * in the correct order.
+     * in proper sequence (from first to last element).
+     *
+     * <p>The returned array will be "safe" in that no references to it are
+     * maintained by this list.  (In other words, this method must allocate
+     * a new array).  The caller is thus free to modify the returned array.
+     * 
+     * <p>This method acts as bridge between array-based and collection-based
+     * APIs.
      *
      * @return an array containing all of the elements in this list
-     *         in the correct order.
+     *         in proper sequence
      */
     public Object[] toArray() {
 	Object[] result = new Object[size];
@@ -844,24 +844,40 @@ public class LinkedList<E>
 
     /**
      * Returns an array containing all of the elements in this list in
-     * the correct order; the runtime type of the returned array is that of
-     * the specified array.  If the list fits in the specified array, it
-     * is returned therein.  Otherwise, a new array is allocated with the
-     * runtime type of the specified array and the size of this list.<p>
-     *
-     * If the list fits in the specified array with room to spare
-     * (i.e., the array has more elements than the list),
-     * the element in the array immediately following the end of the
-     * collection is set to null.  This is useful in determining the length
-     * of the list <i>only</i> if the caller knows that the list
-     * does not contain any null elements.
+     * proper sequence (from first to last element); the runtime type of
+     * the returned array is that of the specified array.  If the list fits
+     * in the specified array, it is returned therein.  Otherwise, a new
+     * array is allocated with the runtime type of the specified array and
+     * the size of this list.
+     *
+     * <p>If the list fits in the specified array with room to spare (i.e.,
+     * the array has more elements than the list), the element in the array
+     * immediately following the end of the list is set to <tt>null</tt>.
+     * (This is useful in determining the length of the list <i>only</i> if
+     * the caller knows that the list does not contain any null elements.)
+     *
+     * <p>Like the {@link #toArray()} method, this method acts as bridge between
+     * array-based and collection-based APIs.  Further, this method allows
+     * precise control over the runtime type of the output array, and may,
+     * under certain circumstances, be used to save allocation costs.
+     *
+     * <p>Suppose <tt>x</tt> is a list known to contain only strings.
+     * The following code can be used to dump the list into a newly
+     * allocated array of <tt>String</tt>:
+     *
+     * <pre>
+     *     String[] y = x.toArray(new String[0]);</pre>
+     *
+     * Note that <tt>toArray(new Object[0])</tt> is identical in function to
+     * <tt>toArray()</tt>.
      *
      * @param a the array into which the elements of the list are to
      *          be stored, if it is big enough; otherwise, a new array of the
      *          same runtime type is allocated for this purpose.
      * @return an array containing the elements of the list
-     * @throws ArrayStoreException if the runtime type of a is not a
-     *         supertype of the runtime type of every element in this list
+     * @throws ArrayStoreException if the runtime type of the specified array
+     *         is not a supertype of the runtime type of every element in
+     *         this list
      * @throws NullPointerException if the specified array is null
      */
     public <T> T[] toArray(T[] a) {