LUCENE-1575: clarify that certain float values are invalid scores

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

CHANGES.txt

@@ -27,7 +27,11 @@ Changes in backwards compatibility policy
     implement Searchable or extend Searcher, you should change you
     code to implement this method.  If you already extend
     IndexSearcher, no further changes are needed to use Collector.
-    (Shai Erera via Mike McCandless)
+    
+    Finally, the values Float.Nan, Float.NEGATIVE_INFINITY and
+    Float.POSITIVE_INFINITY are not valid scores.  Lucene uses these
+    values internally in certain places, so if you have hits with such
+    scores it will cause problems. (Shai Erera via Mike McCandless)
 
 Changes in runtime behavior
 

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

@@ -31,6 +31,13 @@ import java.io.IOException;
  * Document scores are computed using a given <code>Similarity</code>
  * implementation.
  * </p>
+ *
+ * <p><b>NOTE</b>: The values Float.Nan,
+ * Float.NEGATIVE_INFINITY and Float.POSITIVE_INFINITY are
+ * not valid scores.  Certain collectors (eg {@link
+ * TopScoreDocCollector}) will not properly collect hits
+ * with these scores.
+ *
  * @see BooleanQuery#setAllowDocsOutOfOrder
  */
 public abstract class Scorer extends DocIdSetIterator {

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

@@ -28,6 +28,11 @@ import org.apache.lucene.index.IndexReader;
  * and then (when the scores are tied) docID ascending. When you create an
  * instance of this collector you should know in advance whether documents are
  * going to be collected in doc Id order or not.
+ *
+ * <p><b>NOTE</b>: The values Float.Nan,
+ * Float.NEGATIVE_INFINITY and Float.POSITIVE_INFINITY are
+ * not valid scores.  This collector will not properly
+ * collect hits with such scores.
  */
 public abstract class TopScoreDocCollector extends TopDocsCollector {