svn commit: r1375332 - /lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/DocIdSetIterator.java

[mi...@apache.org]

Author: mikemccand
Date: Mon Aug 20 23:56:43 2012
New Revision: 1375332

URL: http://svn.apache.org/viewvc?rev=1375332&view=rev
Log:
LUCENE-4313: make it clear that DISI.advance behavior is undefined if target <= current

Modified:
    lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/DocIdSetIterator.java

Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/DocIdSetIterator.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/DocIdSetIterator.java?rev=1375332&r1=1375331&r2=1375332&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/DocIdSetIterator.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/search/DocIdSetIterator.java Mon Aug 20 23:56:43 2012
@@ -60,13 +60,17 @@ public abstract class DocIdSetIterator {
    */
   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 @@ public abstract class DocIdSetIterator {
    * 
    * 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;