--- jsr166/src/main/java/util/Deque.java	2005/05/14 02:22:28	1.8
+++ jsr166/src/main/java/util/Deque.java	2005/06/18 01:56:01	1.14
@@ -5,6 +5,7 @@
  */
 
 package java.util;
+import java.util.*; // for javadoc
 
 /**
  * A linear collection that supports element insertion and removal at
@@ -172,28 +173,30 @@ public interface Deque<E> extends Queue<
      * @param e the element to add
      * @throws IllegalStateException if the element cannot be added at this
      *         time due to capacity restrictions
-     * @throws NullPointerException if the specified element is null and this
-     *         deque does not permit null elements
      * @throws ClassCastException if the class of the specified element
      *         prevents it from being added to this deque
+     * @throws NullPointerException if the specified element is null and this
+     *         deque does not permit null elements
      * @throws IllegalArgumentException if some property of the specified
      *         element prevents it from being added to this deque
      */
     void addFirst(E e);
 
     /**
-     * Inserts the specified element at the end of this deque  if it is
+     * Inserts the specified element at the end of this deque if it is
      * possible to do so immediately without violating capacity restrictions.
      * When using a capacity-restricted deque, it is generally preferable to
      * use method {@link #offerLast}.
      *
+     * <p>This method is equivalent to {@link #add}.
+     *
      * @param e the element to add
      * @throws IllegalStateException if the element cannot be added at this
      *         time due to capacity restrictions
-     * @throws NullPointerException if the specified element is null and this
-     *         deque does not permit null elements
      * @throws ClassCastException if the class of the specified element
      *         prevents it from being added to this deque
+     * @throws NullPointerException if the specified element is null and this
+     *         deque does not permit null elements
      * @throws IllegalArgumentException if some property of the specified
      *         element prevents it from being added to this deque
      */
@@ -206,12 +209,12 @@ public interface Deque<E> extends Queue<
      * which can fail to insert an element only by throwing an exception.
      *
      * @param e the element to add
-     * @return <tt>true</tt> if it was possible to insert the element,
-     *         else <tt>false</tt>
-     * @throws NullPointerException if the specified element is null and this
-     *         deque does not permit null elements
+     * @return <tt>true</tt> if the element was added to this deque, else
+     *         <tt>false</tt>
      * @throws ClassCastException if the class of the specified element
      *         prevents it from being added to this deque
+     * @throws NullPointerException if the specified element is null and this
+     *         deque does not permit null elements
      * @throws IllegalArgumentException if some property of the specified
      *         element prevents it from being added to this deque
      */
@@ -224,12 +227,12 @@ public interface Deque<E> extends Queue<
      * which can fail to insert an element only by throwing an exception.
      *
      * @param e the element to add
-     * @return <tt>true</tt> if it was possible to insert the element,
-     *         else <tt>false</tt>
-     * @throws NullPointerException if the specified element is null and this
-     *         deque does not permit null elements
+     * @return <tt>true</tt> if the element was added to this deque, else
+     *         <tt>false</tt>
      * @throws ClassCastException if the class of the specified element
      *         prevents it from being added to this deque
+     * @throws NullPointerException if the specified element is null and this
+     *         deque does not permit null elements
      * @throws IllegalArgumentException if some property of the specified
      *         element prevents it from being added to this deque
      */
@@ -311,16 +314,17 @@ public interface Deque<E> extends Queue<
      * Removes the first occurrence of the specified element from this deque.
      * If the deque does not contain the element, it is unchanged.
      * More formally, removes the first element <tt>e</tt> such that
-     * <tt>(o==null ? e==null : o.equals(e))</tt> (if such an element exists).
-     * Returns true if this deque contained the specified element (or
-     * equivalently, if this deque changed as a result of the call).
+     * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
+     * (if such an element exists).
+     * Returns <tt>true</tt> if this deque contained the specified element
+     * (or equivalently, if this deque changed as a result of the call).
      *
      * @param o element to be removed from this deque, if present
      * @return <tt>true</tt> if an element was removed as a result of this call
+     * @throws ClassCastException if the class of the specified element
+     *         is incompatible with this deque (optional)
      * @throws NullPointerException if the specified element is null and this
      *         deque does not permit null elements (optional)
-     * @throws ClassCastException if the class of the specified element
-     *         is incompatible with this collection (optional)
      */
     boolean removeFirstOccurrence(Object o);
 
@@ -328,16 +332,17 @@ public interface Deque<E> extends Queue<
      * Removes the last occurrence of the specified element from this deque.
      * If the deque does not contain the element, it is unchanged.
      * More formally, removes the last element <tt>e</tt> such that
-     * <tt>(o==null ? e==null : o.equals(e))</tt> (if such an element exists).
-     * Returns true if this deque contained the specified element (or
-     * equivalently, if this deque changed as a result of the call).
+     * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
+     * (if such an element exists).
+     * Returns <tt>true</tt> if this deque contained the specified element
+     * (or equivalently, if this deque changed as a result of the call).
      *
      * @param o element to be removed from this deque, if present
      * @return <tt>true</tt> if an element was removed as a result of this call
+     * @throws ClassCastException if the class of the specified element
+     *         is incompatible with this deque (optional)
      * @throws NullPointerException if the specified element is null and this
      *         deque does not permit null elements (optional)
-     * @throws ClassCastException if the class of the specified element
-     *         is incompatible with this collection (optional)
      */
     boolean removeLastOccurrence(Object o);
 
@@ -352,16 +357,16 @@ public interface Deque<E> extends Queue<
      * When using a capacity-restricted deque, it is generally preferable to
      * use {@link #offer(Object) offer}.
      *
-     * <p>This method is equivalent to {@link #addLast(Object) addLast}.
+     * <p>This method is equivalent to {@link #addLast}.
      *
      * @param e the element to add
      * @return <tt>true</tt> (as per the spec for {@link Collection#add})
      * @throws IllegalStateException if the element cannot be added at this
      *         time due to capacity restrictions
-     * @throws NullPointerException if the specified element is null and this
-     *         deque does not permit null elements
      * @throws ClassCastException if the class of the specified element
      *         prevents it from being added to this deque
+     * @throws NullPointerException if the specified element is null and this
+     *         deque does not permit null elements
      * @throws IllegalArgumentException if some property of the specified
      *         element prevents it from being added to this deque
      */
@@ -381,10 +386,10 @@ public interface Deque<E> extends Queue<
      * @param e the element to add
      * @return <tt>true</tt> if the element was added to this deque, else
      *         <tt>false</tt>
-     * @throws NullPointerException if the specified element is null and this
-     *         deque does not permit null elements
      * @throws ClassCastException if the class of the specified element
      *         prevents it from being added to this deque
+     * @throws NullPointerException if the specified element is null and this
+     *         deque does not permit null elements
      * @throws IllegalArgumentException if some property of the specified
      *         element prevents it from being added to this deque
      */
@@ -455,10 +460,10 @@ public interface Deque<E> extends Queue<
      * @param e the element to push
      * @throws IllegalStateException if the element cannot be added at this
      *         time due to capacity restrictions
-     * @throws NullPointerException if the specified element is null and this
-     *         deque does not permit null elements
      * @throws ClassCastException if the class of the specified element
      *         prevents it from being added to this deque
+     * @throws NullPointerException if the specified element is null and this
+     *         deque does not permit null elements
      * @throws IllegalArgumentException if some property of the specified
      *         element prevents it from being added to this deque
      */
@@ -483,26 +488,27 @@ public interface Deque<E> extends Queue<
      * Removes the first occurrence of the specified element from this deque.
      * If the deque does not contain the element, it is unchanged.
      * More formally, removes the first element <tt>e</tt> such that
-     * <tt>(o==null ? e==null : o.equals(e))</tt> (if such an element exists).
-     * Returns true if this deque contained the specified element (or
-     * equivalently, if this deque changed as a result of the call).
+     * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>
+     * (if such an element exists).
+     * Returns <tt>true</tt> if this deque contained the specified element
+     * (or equivalently, if this deque changed as a result of the call).
      *
      * <p>This method is equivalent to {@link #removeFirstOccurrence}.
      *
      * @param o element to be removed from this deque, if present
      * @return <tt>true</tt> if an element was removed as a result of this call
+     * @throws ClassCastException if the class of the specified element
+     *         is incompatible with this deque (optional)
      * @throws NullPointerException if the specified element is null and this
      *         deque does not permit null elements (optional)
-     * @throws ClassCastException if the class of the specified element
-     *         is incompatible with this collection (optional)
      */
     boolean remove(Object o);
 
     /**
      * Returns <tt>true</tt> if this deque contains the specified element.
-     * More formally, returns <tt>true</tt> if and only if this deque
-     * contains at least one element <tt>e</tt> such that <tt>(o==null ? 
-     * e==null : o.equals(e))</tt>.
+     * More formally, returns <tt>true</tt> if and only if this deque contains
+     * 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 deque is to be tested
      * @return <tt>true</tt> if this deque contains the specified element
@@ -521,10 +527,10 @@ public interface Deque<E> extends Queue<
     public int size();
 
     /**
-     * Returns an iterator over the elements in this deque.  The elements
-     * will be ordered from first (head) to last (tail).
+     * Returns an iterator over the elements in this deque in proper sequence.
+     * The elements will be returned in order from first (head) to last (tail).
      *
-     * @return an <tt>Iterator</tt> over the elements in this deque
+     * @return an iterator over the elements in this deque in proper sequence
      */
     Iterator<E> iterator();
 }