From 6a1f2d5729a41f64c09b84b50ea1bb38798eb84a Mon Sep 17 00:00:00 2001
From: Michael McCandless <mikemccand@apache.org>
Date: Mon, 26 Oct 2009 18:04:22 +0000
Subject: [PATCH] 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                                         |  4 ++++
 .../org/apache/lucene/search/IndexSearcher.java     | 13 ++++++++++++-
 src/java/org/apache/lucene/search/Searchable.java   |  2 +-
 src/java/org/apache/lucene/search/Searcher.java     |  8 +++-----
 4 files changed, 20 insertions(+), 7 deletions(-)

diff --git a/CHANGES.txt b/CHANGES.txt
index 86718b34e3b..5d53f62ea85 100644
--- a/CHANGES.txt
+++ b/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
diff --git a/src/java/org/apache/lucene/search/IndexSearcher.java b/src/java/org/apache/lucene/search/IndexSearcher.java
index 1b00cca1865..5f47c59f69d 100644
--- a/src/java/org/apache/lucene/search/IndexSearcher.java
+++ b/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;
diff --git a/src/java/org/apache/lucene/search/Searchable.java b/src/java/org/apache/lucene/search/Searchable.java
index f6bc747d91e..46c2ef3a56c 100644
--- a/src/java/org/apache/lucene/search/Searchable.java
+++ b/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
    */
diff --git a/src/java/org/apache/lucene/search/Searcher.java b/src/java/org/apache/lucene/search/Searcher.java
index a41e2a82f38..fc32010e7d4 100644
--- a/src/java/org/apache/lucene/search/Searcher.java
+++ b/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
-   * you need scores, create a {@link TopFieldCollector}
-   * instance by calling {@link TopFieldCollector#create}
-   * and then pass that to {@link #search(Query, Filter,
-   * Collector)}.</p>
+   * <p>NOTE: this does not compute scores by default; use
+   * {@link IndexSearcher#setDefaultFieldSortScoring} to
+   * enable scoring.
    *
    * @throws BooleanQuery.TooManyClauses
    */