LUCENE-1973: un-deprecate IndexSearcher.setDefaultFieldSortScoring

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

CHANGES.txt

@@ -103,6 +103,10 @@ API Changes
   of 2.9) enablePositionIncrements to true to match
   StandardAnalyzer's 2.9 default (Uwe Schindler, Mike McCandless)
 
+* LUCENE-1973: Un-deprecate IndexSearcher.setDefaultFieldSortScoring,
+  to allow controlling per-IndexSearcher whether scores are computed
+  when sorting by field.  (Uwe Schindler, Mike McCandless)
+   
 Bug fixes
 
 * LUCENE-1951: When the text provided to WildcardQuery has no wildcard

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

@@ -270,7 +270,18 @@ public class IndexSearcher extends Searcher {
   private boolean fieldSortDoTrackScores;
   private boolean fieldSortDoMaxScore;
 
-  /** @deprecated */
+  /** By default, no scores are computed when sorting by
+   *  field (using {@link #search(Query,Filter,int,Sort)}).
+   *  You can change that, per IndexSearcher instance, by
+   *  calling this method.  Note that this will incur a CPU
+   *  cost.
+   * 
+   *  @param doTrackScores If true, then scores are
+   *  returned for every matching document in {@link
+   *  TopFieldDocs}.
+   *
+   *  @param doMaxScore If true, then the max score for all
+   *  matching docs is computed. */
   public void setDefaultFieldSortScoring(boolean doTrackScores, boolean doMaxScore) {
     fieldSortDoTrackScores = doTrackScores;
     fieldSortDoMaxScore = doMaxScore;

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

@@ -155,7 +155,7 @@ public interface Searchable extends Closeable {
    * <code>sort</code>.
    *
    * <p>Applications should usually call {@link
-   * Searcher#search(Query,Filter,Sort)} instead.
+   * Searcher#search(Query,Filter,int,Sort)} instead.
    * 
    * @throws BooleanQuery.TooManyClauses
    */

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

@@ -37,11 +37,9 @@ public abstract class Searcher implements Searchable {
    * <code>filter</code> if non-null, and sorting the hits by the criteria in
    * <code>sort</code>.
    * 
-   * <p>NOTE: this does not compute scores by default.  If
+   * <p>NOTE: this does not compute scores by default; use
-   * you need scores, create a {@link TopFieldCollector}
+   * {@link IndexSearcher#setDefaultFieldSortScoring} to
-   * instance by calling {@link TopFieldCollector#create}
+   * enable scoring.
-   * and then pass that to {@link #search(Query, Filter,
-   * Collector)}.</p>
    *
    * @throws BooleanQuery.TooManyClauses
    */