more explicit javadocs about Scorer contract for iterating in doc id order

git-svn-id: https://svn.apache.org/repos/asf/lucene/java/trunk@582054 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/lucene/search/BooleanQuery.java

@@ -313,15 +313,25 @@ public class BooleanQuery extends Query {
   private static boolean allowDocsOutOfOrder = false;
 
   /**
-   * Indicates whether hit docs may be collected out of docid
+   * Expert: Indicates whether hit docs may be collected out of docid
-   * order. In other words, with this setting, 
+   * order.
+   *
+   * <p>
+   * Background: llthough the contract of the Scorer class requires that
+   * documents be iterated in order of doc id this was not true in early
+   * versions of Lucene.  Many pieces of functionality in the current
+   * Lucene code base have undefined behavior if this contract is not
+   * upheld, but in some specific simple cases may be faster.  (For
+   * example: disjunction queries with less than 32 prohibited clauses;
+   * This setting has no effect for other queries.)
+   * </p>
+   *
+   * <p>
+   * Specifics: By setting this option to this true, calls to 
    * {@link HitCollector#collect(int,float)} might be
    * invoked first for docid N and only later for docid N-1.
    * Being static, this setting is system wide.
-   * If collecting docs out of order is allowed, scoring might be faster
+   * </p>
-   * for certain queries, for example disjunction queries with
-   * less than 32 prohibited clauses.
-   * This setting has no effect for other queries.
    */
   public static void setAllowDocsOutOfOrder(boolean allow) {
     allowDocsOutOfOrder = allow;

src/java/org/apache/lucene/search/Scorer.java

@@ -19,10 +19,19 @@ package org.apache.lucene.search;
 
 import java.io.IOException;
 
-/** Expert: Common scoring functionality for different types of queries.
+/**
- * <br>A <code>Scorer</code> either iterates over documents matching a query,
+ * Expert: Common scoring functionality for different types of queries.
- * or provides an explanation of the score for a query for a given document.
+ *
- * <br>Document scores are computed using a given <code>Similarity</code> implementation.
+ * <p>
+ * A <code>Scorer</code> either iterates over documents matching a
+ * query in increasing order of doc Id, or provides an explanation of
+ * the score for a query for a given document.
+ * </p>
+ * <p>
+ * Document scores are computed using a given <code>Similarity</code>
+ * implementation.
+ * </p>
+ * @see BooleanQuery#setAllowDocsOutOfOrder
  */
 public abstract class Scorer {
   private Similarity similarity;
@@ -67,9 +76,19 @@ public abstract class Scorer {
     return true;
   }
 
-  /** Advances to the next document matching the query.
+  /**
+   * Advances to the document matching this Scorer with the lowest doc Id
+   * greater then the current value of {@link doc()} (or to the matching
+   * document with the lowest doc Id if next has never been called on
+   * this Scorer).
+   *
+   * <p>
+   * When this method is used the {@link #explain(int)} method should not
+   * be used.
+   * </p>
+   *
    * @return true iff there is another document matching the query.
-   * <br>When this method is used the {@link #explain(int)} method should not be used.
+   * @see BooleanQuery#setAllowDocsOutOfOrder
    */
   public abstract boolean next() throws IOException;
 
@@ -84,12 +103,16 @@ public abstract class Scorer {
    */
   public abstract float score() throws IOException;
 
-  /** Skips to the first match beyond the current whose document number is
+  /**
+   * Skips to the document matching this Scorer with the lowest doc Id
    * greater than or equal to a given target.
-   * <br>When this method is used the {@link #explain(int)} method should not be used.
+   *
-   * @param target The target document number.
+   * <p>
-   * @return true iff there is such a match.
+   * The behavior of this method is undefined if the target specified is
-   * <p>Behaves as if written: <pre>
+   * less then or equal to the current value of {@link #doc()}
+   * <p>
+   * Behaves as if written:
+   * <pre>
    *   boolean skipTo(int target) {
    *     do {
    *       if (!next())
@@ -97,7 +120,18 @@ public abstract class Scorer {
    *     } while (target > doc());
    *     return true;
    *   }
-   * </pre>Most implementations are considerably more efficient than that.
+   * </pre>
+   * Most implementations are considerably more efficient than that.
+   * </p>
+   *
+   * <p>
+   * When this method is used the {@link #explain(int)} method should not
+   * be used.
+   * </p>
+   *
+   * @param target The target document number.
+   * @return true iff there is such a match.
+   * @see BooleanQuery#setAllowDocsOutOfOrder
    */
   public abstract boolean skipTo(int target) throws IOException;