From 4a85c3dd03f583d15f6b7d6eebbc2254febf918a Mon Sep 17 00:00:00 2001
From: Adrien Grand <jpountz@apache.org>
Date: Thu, 25 Jun 2015 17:21:08 +0000
Subject: [PATCH] LUCENE-6553: Fixes to Weight's javadoc.

git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1687586 13f79535-47bb-0310-9956-ffa450edef68
---
 .../core/src/java/org/apache/lucene/search/Weight.java | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/lucene/core/src/java/org/apache/lucene/search/Weight.java b/lucene/core/src/java/org/apache/lucene/search/Weight.java
index f00327be29c..e653a317ef9 100644
--- a/lucene/core/src/java/org/apache/lucene/search/Weight.java
+++ b/lucene/core/src/java/org/apache/lucene/search/Weight.java
@@ -21,6 +21,7 @@ import java.io.IOException;
 import java.util.Set;
 
 import org.apache.lucene.index.IndexReaderContext;
+import org.apache.lucene.index.LeafReader;
 import org.apache.lucene.index.LeafReaderContext;
 import org.apache.lucene.index.Term;
 import org.apache.lucene.search.similarities.Similarity;
@@ -97,11 +98,14 @@ public abstract class Weight {
   public abstract void normalize(float norm, float topLevelBoost);
 
   /**
-   * Returns a {@link Scorer} which scores documents in/out-of order according
-   * to <code>scoreDocsInOrder</code>.
+   * Returns a {@link Scorer} which can iterate in order over all matching
+   * documents and assign them a score.
    * <p>
    * <b>NOTE:</b> null can be returned if no documents will be scored by this
    * query.
+   * <p>
+   * <b>NOTE</b>: The returned {@link Scorer} does not have
+   * {@link LeafReader#getLiveDocs()} applied, they need to be checked on top.
    * 
    * @param context
    *          the {@link org.apache.lucene.index.LeafReaderContext} for which to return the {@link Scorer}.
@@ -117,7 +121,7 @@ public abstract class Weight {
    * Only queries that have a different top-level approach
    * need to override this; the default implementation
    * pulls a normal {@link Scorer} and iterates and
-   * collects the resulting hits.
+   * collects the resulting hits which are not marked as deleted.
    *
    * @param context
    *          the {@link org.apache.lucene.index.LeafReaderContext} for which to return the {@link Scorer}.