- Added javadoc to setTermIndexInterval (from Doug's email)

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

src/java/org/apache/lucene/index/IndexWriter.java

@@ -169,10 +169,21 @@ public class IndexWriter {
   /** Expert: Set the interval between indexed terms.  Large values cause less
    * memory to be used by IndexReader, but slow random-access to terms.  Small
    * values cause more memory to be used by an IndexReader, and speed
-   * random-access to terms.  In particular,
+   * random-access to terms.
-   * <code>numUniqueTerms/interval</code> terms are read into memory by an
+   *
-   * IndexReader, and, on average, <code>interval/2</code> terms must be
+   * This parameter determines the amount of computation required per query
-   * scanned for each random term access.
+   * term, regardless of the number of documents that contain that term.  In
+   * particular, it is the maximum number of other terms that must be
+   * scanned before a term is located and its frequency and position information
+   * may be processed.  In a large index with user-entered query terms, query
+   * processing time is likely to be dominated not by term lookup but rather
+   * by the processing of frequency and positional data.  In a small index
+   * or when many uncommon query terms are generated (e.g., by wildcard
+   * queries) term lookup may become a dominant cost.
+   *
+   * In particular, <code>numUniqueTerms/interval</code> terms are read into
+   * memory by an IndexReader, and, on average, <code>interval/2</code> terms
+   * must be scanned for each random term access.
    *
    * @see #DEFAULT_TERM_INDEX_INTERVAL
    */