clarify constantScoreRewrite for MultiTermQuery/RangeQuery

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

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

@@ -22,21 +22,29 @@ import java.io.IOException;
 import org.apache.lucene.index.IndexReader;
 import org.apache.lucene.index.Term;
 import org.apache.lucene.util.ToStringUtils;
+import org.apache.lucene.queryParser.QueryParser; // for javadoc
 
 /**
- * A {@link Query} that matches documents containing a subset of terms provided
- * by a {@link FilteredTermEnum} enumeration.
- * <P>
- * <code>MultiTermQuery</code> is not designed to be used by itself. <BR>
- * The reason being that it is not intialized with a {@link FilteredTermEnum}
- * enumeration. A {@link FilteredTermEnum} enumeration needs to be provided.
- * <P>
- * For example, {@link WildcardQuery} and {@link FuzzyQuery} extend
- * <code>MultiTermQuery</code> to provide {@link WildcardTermEnum} and
- * {@link FuzzyTermEnum}, respectively.
+ * An abstract {@link Query} that matches documents
+ * containing a subset of terms provided by a {@link
+ * FilteredTermEnum} enumeration.
  *
- * The pattern Term may be null. A query that uses a null pattern Term should
- * override equals and hashcode.
+ * <p>This query cannot be used directly; you must subclass
+ * it and define {@link #getEnum} to provide a {@link
+ * FilteredTermEnum} that iterates through the terms to be
+ * matched.
+ *
+ * <p><b>NOTE</b>: if {@link #setConstantScoreRewrite} is
+ * false, you may encounter a {@link
+ * BooleanQuery.TooManyClauses} exception during searching,
+ * which happens when the number of terms to be searched
+ * exceeds {@link BooleanQuery#getMaxClauseCount()}.
+ * Setting {@link #setConstantScoreRewrite} to false
+ * prevents this.
+ *
+ * Note that {@link QueryParser} by default produces
+ * MultiTermQueries with {@link #setConstantScoreRewrite}
+ * true.
  */
 public abstract class MultiTermQuery extends Query {
   /* @deprecated move to sub class */
@@ -146,10 +154,33 @@ public abstract class MultiTermQuery extends Query {
     return buffer.toString();
   }
 
+  /**
+   * @see #setConstantScoreRewrite
+   */
   public boolean getConstantScoreRewrite() {
     return constantScoreRewrite;
   }
 
+  /**
+   * This method determines what method is used during searching:
+   * <ul>
+   *
+   *   <li> When constantScoreRewrite is <code>false</code>
+   *   (the default), the query is rewritten to {@link
+   *   BooleanQuery} with one clause for each term in the
+   *   range.  If the the number of terms in the range
+   *   exceeds {@link BooleanQuery#getMaxClauseCount()}, a
+   *   {@link BooleanQuery.TooManyClauses} exception will be
+   *   thrown during searching.  This mode may also give
+   *   worse performance when the number of terms is large,
+   *   and/or the number of matching documents is large.
+   *
+   *   <li> When constantScoreRewrite is <code>true</code>,
+   *   the query is first rewritten to a filter.  Matching
+   *   documents will identical scores, equal to this
+   *   query's boost.
+   * </ul>
+   */
   public void setConstantScoreRewrite(boolean constantScoreRewrite) {
     this.constantScoreRewrite = constantScoreRewrite;
   }

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

@@ -24,19 +24,12 @@ import org.apache.lucene.index.Term;
 import org.apache.lucene.index.IndexReader;
 
 /**
- * A Query that matches documents within an exclusive range. A RangeQuery
- * is built by QueryParser for input like <code>[010 TO 120]</code> but only if the QueryParser has 
- * the useOldRangeQuery property set to true. The QueryParser default behaviour is to use
- * the newer ConstantScore mode. This is generally preferable because:
- * <ul>
- *  <li>In certain situations, it may be faster than the standard RangeQuery mode</li>
- *  <li>Unlike the RangeQuery mode, it does not cause a BooleanQuery.TooManyClauses exception if the range of values is large</li>
- *  <li>Unlike the RangeQuery mode, it does not influence scoring based on the scarcity of individual terms that may match</li>
- * </ul>
+ * A Query that matches documents within an exclusive range.
  *
- *
- * @version $Id$
+ * See {@link MultiTermQuery#setConstantScoreRewrite} for the tradeoffs between
+ * enabling and disabling constantScoreRewrite mode.
  */
+
 public class RangeQuery extends MultiTermQuery {
   private Term lowerTerm;
   private Term upperTerm;