--- jsr166/src/main/java/util/NavigableSet.java	2006/04/21 23:11:14	1.22
+++ jsr166/src/main/java/util/NavigableSet.java	2013/02/09 20:41:56	1.27
@@ -1,15 +1,15 @@
 /*
  * Written by Doug Lea and Josh Bloch with assistance from members of JCP
  * JSR-166 Expert Group and released to the public domain, as explained at
- * http://creativecommons.org/licenses/publicdomain
+ * http://creativecommons.org/publicdomain/zero/1.0/
  */
 
 package java.util;
 
 /**
  * A {@link SortedSet} extended with navigation methods reporting
- * closest matches for given search targets. Methods {@code lower},
- * {@code floor}, {@code ceiling}, and {@code higher} return elements
+ * closest matches for given search targets. Methods {@link #lower},
+ * {@link #floor}, {@link #ceiling}, and {@link #higher} return elements
  * respectively less than, less than or equal, greater than or equal,
  * and greater than a given element, returning {@code null} if there
  * is no such element.  A {@code NavigableSet} may be accessed and
@@ -18,7 +18,7 @@ package java.util;
  * all relational and directional methods inverted. The performance of
  * ascending operations and views is likely to be faster than that of
  * descending ones.  This interface additionally defines methods
- * {@code pollFirst} and {@code pollLast} that return and remove the
+ * {@link #pollFirst} and {@link #pollLast} that return and remove the
  * lowest and highest element, if one exists, else returning {@code
  * null}.  Methods {@code subSet}, {@code headSet},
  * and {@code tailSet} differ from the like-named {@code
@@ -27,7 +27,7 @@ package java.util;
  * Subsets of any {@code NavigableSet} must implement the {@code
  * NavigableSet} interface.
  *
- * <p> The return values of navigation methods may be ambiguous in
+ * <p>The return values of navigation methods may be ambiguous in
  * implementations that permit {@code null} elements. However, even
  * in this case the result can be disambiguated by checking
  * {@code contains(null)}. To avoid such issues, implementations of
@@ -35,8 +35,18 @@ package java.util;
  * {@code null} elements. (Note that sorted sets of {@link
  * Comparable} elements intrinsically do not permit {@code null}.)
  *
+ * <p>Methods
+ * {@link #subSet(Object, Object) subSet(E, E)},
+ * {@link #headSet(Object) headSet(E)}, and
+ * {@link #tailSet(Object) tailSet(E)}
+ * are specified to return {@code SortedSet} to allow existing
+ * implementations of {@code SortedSet} to be compatibly retrofitted to
+ * implement {@code NavigableSet}, but extensions and implementations
+ * of this interface are encouraged to override these methods to return
+ * {@code NavigableSet}.
+ *
  * <p>This interface is a member of the
- * <a href="{@docRoot}/../guide/collections/index.html">
+ * <a href="{@docRoot}/../technotes/guides/collections/index.html">
  * Java Collections Framework</a>.
  *
  * @author Doug Lea
@@ -125,15 +135,19 @@ public interface NavigableSet<E> extends
     Iterator<E> iterator();
 
     /**
-     * Returns a {@link NavigableSet} view of the elements contained in this
-     * set in descending order.  The descending set is backed by this set, so
-     * changes to the set are reflected in the descending set, and vice-versa.
-     * If either set is modified while an iteration over the other set is in
-     * progress (except through the iterator's own {@code remove} operation),
-     * the results of the iteration are undefined.
+     * Returns a reverse order view of the elements contained in this set.
+     * The descending set is backed by this set, so changes to the set are
+     * reflected in the descending set, and vice-versa.  If either set is
+     * modified while an iteration over either set is in progress (except
+     * through the iterator's own {@code remove} operation), the results of
+     * the iteration are undefined.
+     *
+     * <p>The returned set has an ordering equivalent to
+     * <tt>{@link Collections#reverseOrder(Comparator) Collections.reverseOrder}(comparator())</tt>.
+     * The expression {@code s.descendingSet().descendingSet()} returns a
+     * view of {@code s} essentially equivalent to {@code s}.
      *
-     * @return a navigable set view of the elements contained in this set,
-     *         sorted in descending order
+     * @return a reverse order view of this set
      */
     NavigableSet<E> descendingSet();
 
@@ -242,10 +256,9 @@ public interface NavigableSet<E> extends
     NavigableSet<E> tailSet(E fromElement, boolean inclusive);
 
     /**
-     * Equivalent to {@code subSet(fromElement, true, toElement, false)}
-     * but with a return type conforming to the {@code SortedSet} interface.
+     * {@inheritDoc}
      *
-     * <p>{@inheritDoc}
+     * <p>Equivalent to {@code subSet(fromElement, true, toElement, false)}.
      *
      * @throws ClassCastException       {@inheritDoc}
      * @throws NullPointerException     {@inheritDoc}
@@ -254,22 +267,20 @@ public interface NavigableSet<E> extends
     SortedSet<E> subSet(E fromElement, E toElement);
 
     /**
-     * Equivalent to {@code headSet(toElement, false)}
-     * but with a return type conforming to the {@code SortedSet} interface.
+     * {@inheritDoc}
      *
-     * <p>{@inheritDoc}
+     * <p>Equivalent to {@code headSet(toElement, false)}.
      *
      * @throws ClassCastException       {@inheritDoc}
      * @throws NullPointerException     {@inheritDoc}
      * @throws IllegalArgumentException {@inheritDoc}
-     */
+na     */
     SortedSet<E> headSet(E toElement);
 
     /**
-     * Equivalent to {@code tailSet(fromElement, true)}
-     * but with a return type conforming to the {@code SortedSet} interface.
+     * {@inheritDoc}
      *
-     * <p>{@inheritDoc}
+     * <p>Equivalent to {@code tailSet(fromElement, true)}.
      *
      * @throws ClassCastException       {@inheritDoc}
      * @throws NullPointerException     {@inheritDoc}