diff --git a/src/java/org/apache/lucene/search/IndexSearcher.java b/src/java/org/apache/lucene/search/IndexSearcher.java
index 435b747e37e..c0ecb590404 100644
--- a/src/java/org/apache/lucene/search/IndexSearcher.java
+++ b/src/java/org/apache/lucene/search/IndexSearcher.java
@@ -161,12 +161,13 @@ public class IndexSearcher extends Searcher {
   /**
    * Just like {@link #search(Weight, Filter, int, Sort)}, but you choose
    * whether or not the fields in the returned {@link FieldDoc} instances should
-   * be set by specifying fillFields.<br>
-   * <b>NOTE:</b> currently, this method tracks document scores and sets them in
-   * the returned {@link FieldDoc}, however in 3.0 it will move to not track
-   * document scores. If document scores tracking is still needed, you can use
-   * {@link #search(Weight, Filter, Collector)} and pass in a
-   * {@link TopFieldCollector} instance.
+   * be set by specifying fillFields.
+   *
+   * <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(Weight, Filter,
+   * Collector)}.</p>
    */
   public TopFieldDocs search(Weight weight, Filter filter, final int nDocs,
                              Sort sort, boolean fillFields)
diff --git a/src/java/org/apache/lucene/search/Searcher.java b/src/java/org/apache/lucene/search/Searcher.java
index 2be1cbfd9c9..a41e2a82f38 100644
--- a/src/java/org/apache/lucene/search/Searcher.java
+++ b/src/java/org/apache/lucene/search/Searcher.java
@@ -37,11 +37,11 @@ public abstract class Searcher implements Searchable {
    * <code>filter</code> if non-null, and sorting the hits by the criteria in
    * <code>sort</code>.
    * 
-   * <b>NOTE:</b> currently, this method tracks document scores and sets them in
-   * the returned {@link FieldDoc}, however in 3.0 it will move to not track
-   * document scores. If document scores tracking is still needed, you can use
-   * {@link #search(Weight, Filter, Collector)} and pass in a
-   * {@link TopFieldCollector} instance.
+   * <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>
    *
    * @throws BooleanQuery.TooManyClauses
    */