- Applied patch for bug 26702, attachment 10637

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

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

@@ -19,34 +19,45 @@ package org.apache.lucene.search;
 
 /**
  * Expert: A ScoreDoc which also contains information about
- * how to sort the referenced document.
+ * how to sort the referenced document.  In addition to the
+ * document number and score, this object contains an array
+ * of values for the document from the field(s) used to sort.
+ * For example, if the sort criteria was to sort by fields
+ * "a", "b" then "c", the <code>fields</code> object array
+ * will have three elements, corresponding respectively to
+ * the term values for the document in fields "a", "b" and "c".
+ * The class of each element in the array will be either
+ * Integer, Float or String depending on the type of values
+ * in the terms of each field.
+ *
+ * <p>Created: Feb 11, 2004 1:23:38 PM
  *
- * <p>Created: Feb 11, 2004 1:23:38 PM 
- * 
  * @author  Tim Jones (Nacimiento Software)
  * @since   lucene 1.4
  * @version $Id$
+ * @see ScoreDoc
  * @see TopFieldDocs
  */
 public class FieldDoc
 extends ScoreDoc {
 
-	/** The values which are used to sort the referenced document.
-	 * The order of these will match the original sort criteria given by an
-	 * Sort object.
+	/** Expert: The values which are used to sort the referenced document.
+	 * The order of these will match the original sort criteria given by a
+	 * Sort object.  Each Object will be either an Integer, Float or String,
+	 * depending on the type of values in the terms of the original field.
 	 * @see Sort
 	 * @see Searchable#search(Query,Filter,int,Sort)
 	 */
 	public Object[] fields;
 
-	/** Creates one of these objects with empty sort information. */
+	/** Expert: Creates one of these objects with empty sort information. */
 	public FieldDoc (int doc, float score) {
 		super (doc, score);
 	}
 
-	/** Creates one of these objects with the given sort information. */
+	/** Expert: Creates one of these objects with the given sort information. */
 	public FieldDoc (int doc, float score, Object[] fields) {
 		super (doc, score);
 		this.fields = fields;
 	}
-}
+}

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

@@ -69,8 +69,28 @@ import java.io.Serializable;
  *
  * <p><h3>Memory Usage</h3>
  *
- * See {@link FieldSortedHitQueue FieldSortedHitQueue} for
- * information on the memory requirements of sorting hits.
+ * <p>Sorting uses of caches of term values maintained by the
+ * internal HitQueue(s).  The cache is static and contains an integer
+ * or float array of length <code>IndexReader.maxDoc()</code> for each field
+ * name for which a sort is performed.  In other words, the size of the
+ * cache in bytes is:
+ *
+ * <p><code>4 * IndexReader.maxDoc() * (# of different fields actually used to sort)</code>
+ *
+ * <p>For String fields, the cache is larger: in addition to the
+ * above array, the value of every term in the field is kept in memory.
+ * If there are many unique terms in the field, this could
+ * be quite large.
+ *
+ * <p>Note that the size of the cache is not affected by how many
+ * fields are in the index and <i>might</i> be used to sort - only by
+ * the ones actually used to sort a result set.
+ *
+ * <p>The cache is cleared each time a new <code>IndexReader</code> is
+ * passed in, or if the value returned by <code>maxDoc()</code>
+ * changes for the current IndexReader.  This class is not set up to
+ * be able to efficiently sort hits from more than one index
+ * simultaneously.
  *
  * <p>Created: Feb 12, 2004 10:53:57 AM
  *
@@ -82,9 +102,9 @@ public class Sort
 implements Serializable {
 
 	/** Represents sorting by computed relevance. Using this sort criteria
-	 * returns the same results with slightly more overhead as calling
-	 * Searcher#search() without a sort criteria. */
-	public static final Sort RELEVANCE = new Sort ();
+	 * returns the same results as calling {@link Searcher#search(Query) Searcher#search()}
+	 * without a sort criteria, only with slightly more overhead. */
+	public static final Sort RELEVANCE = new Sort();
 
 	/** Represents sorting by index order. */
 	public static final Sort INDEXORDER = new Sort (SortField.FIELD_DOC);
@@ -94,7 +114,7 @@ implements Serializable {
 
 
 	/** Sorts by computed relevance.  This is the same sort criteria as
-	 * calling Searcher#search() without a sort criteria, only with
+	 * calling {@link Searcher#search(Query) Searcher#search()} without a sort criteria, only with
 	 * slightly more overhead. */
 	public Sort() {
 		this (new SortField[]{SortField.FIELD_SCORE, SortField.FIELD_DOC});
@@ -102,20 +122,30 @@ implements Serializable {
 
 
 	/** Sorts by the terms in <code>field</code> then by index order (document
-	 * number). */
+	 * number). The type of value in <code>field</code> is determined
+	 * automatically.
+	 * @see SortField#AUTO
+	 */
 	public Sort (String field) {
 		setSort (field, false);
 	}
 
 
 	/** Sorts possibly in reverse by the terms in <code>field</code> then by
-	 * index order (document number). */
+	 * index order (document number). The type of value in <code>field</code> is determined
+	 * automatically.
+	 * @see SortField#AUTO
+	 */
 	public Sort (String field, boolean reverse) {
 		setSort (field, reverse);
 	}
 
 
-	/** Sorts in succession by the terms in each field. */
+	/** Sorts in succession by the terms in each field.
+	 * The type of value in <code>field</code> is determined
+	 * automatically.
+	 * @see SortField#AUTO
+	 */
 	public Sort (String[] fields) {
 		setSort (fields);
 	}

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

@@ -27,6 +27,7 @@ import java.io.Serializable;
  * @author  Tim Jones (Nacimiento Software)
  * @since   lucene 1.4
  * @version $Id$
+ * @see Sort
  */
 public class SortField
 implements Serializable {