--- lucene-4.0.0-BETA/core/src/java/org/apache/lucene/search/DocIdSetIterator.java	2012-06-11 15:46:14.000000000 -0400
+++ /tmp/lucene-fix/core/src/java/org/apache/lucene/search/DocIdSetIterator.java	2012-08-20 14:25:55.000000000 -0400
@@ -60,13 +60,17 @@
    */
   public abstract int nextDoc() throws IOException;
 
-  /**
-   * Advances to the first beyond (see NOTE below) the current whose document
-   * number is greater than or equal to <i>target</i>. Returns the current
-   * document number or {@link #NO_MORE_DOCS} if there are no more docs in the
-   * set.
+ /**
+   * Advances to the first beyond the current whose document number is greater 
+   * than or equal to <i>target</i>, and returns the document number itself. 
+   * Exhausts the iterator and returns {@link #NO_MORE_DOCS} if <i>target</i> 
+   * is greater than the highest document number in the set.
    * <p>
-   * Behaves as if written:
+   * The behavior of this method is <b>undefined</b> when called with
+   * <code> target &le; current</code>, or after the iterator has exhausted.
+   * Both cases may result in unpredicted behavior.
+   * <p>
+   * When <code> target &gt; current</code> it behaves as if written:
    * 
    * <pre>
    * int advance(int target) {
@@ -79,18 +83,12 @@
    * 
    * Some implementations are considerably more efficient than that.
    * <p>
-   * <b>NOTE:</b> when <code> target &le; current</code> implementations may opt
-   * not to advance beyond their current {@link #docID()}.
-   * <p>
    * <b>NOTE:</b> this method may be called with {@link #NO_MORE_DOCS} for
    * efficiency by some Scorers. If your implementation cannot efficiently
    * determine that it should exhaust, it is recommended that you check for that
    * value in each call to this method.
    * <p>
-   * <b>NOTE:</b> after the iterator has exhausted you should not call this
-   * method, as it may result in unpredicted behavior.
-   * <p>
-   * 
+   *
    * @since 2.9
    */
   public abstract int advance(int target) throws IOException;