lucene-java-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hoss...@apache.org
Subject svn commit: r582054 - in /lucene/java/trunk/src/java/org/apache/lucene/search: BooleanQuery.java Scorer.java
Date Fri, 05 Oct 2007 01:53:30 GMT
Author: hossman
Date: Thu Oct  4 18:53:29 2007
New Revision: 582054

URL: http://svn.apache.org/viewvc?rev=582054&view=rev
Log:
more explicit javadocs about Scorer contract for iterating in doc id order

Modified:
    lucene/java/trunk/src/java/org/apache/lucene/search/BooleanQuery.java
    lucene/java/trunk/src/java/org/apache/lucene/search/Scorer.java

Modified: lucene/java/trunk/src/java/org/apache/lucene/search/BooleanQuery.java
URL: http://svn.apache.org/viewvc/lucene/java/trunk/src/java/org/apache/lucene/search/BooleanQuery.java?rev=582054&r1=582053&r2=582054&view=diff
==============================================================================
--- lucene/java/trunk/src/java/org/apache/lucene/search/BooleanQuery.java (original)
+++ lucene/java/trunk/src/java/org/apache/lucene/search/BooleanQuery.java Thu Oct  4 18:53:29
2007
@@ -313,15 +313,25 @@
   private static boolean allowDocsOutOfOrder = false;
 
   /**
-   * Indicates whether hit docs may be collected out of docid
-   * order. In other words, with this setting, 
+   * Expert: Indicates whether hit docs may be collected out of docid
+   * 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
-   * for certain queries, for example disjunction queries with
-   * less than 32 prohibited clauses.
-   * This setting has no effect for other queries.
+   * </p>
    */
   public static void setAllowDocsOutOfOrder(boolean allow) {
     allowDocsOutOfOrder = allow;

Modified: lucene/java/trunk/src/java/org/apache/lucene/search/Scorer.java
URL: http://svn.apache.org/viewvc/lucene/java/trunk/src/java/org/apache/lucene/search/Scorer.java?rev=582054&r1=582053&r2=582054&view=diff
==============================================================================
--- lucene/java/trunk/src/java/org/apache/lucene/search/Scorer.java (original)
+++ lucene/java/trunk/src/java/org/apache/lucene/search/Scorer.java Thu Oct  4 18:53:29 2007
@@ -19,10 +19,19 @@
 
 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,
- * 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.
+/**
+ * Expert: Common scoring functionality for different types of queries.
+ *
+ * <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 @@
     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 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.
-   * @return true iff there is such a match.
-   * <p>Behaves as if written: <pre>
+   *
+   * <p>
+   * The behavior of this method is undefined if the target specified is
+   * 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 @@
    *     } 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;
 



Mime
View raw message