Index: Scorer.java
===================================================================
RCS file: /home/cvspublic/jakarta-lucene/src/java/org/apache/lucene/search/Scorer.java,v
retrieving revision 1.6
diff -u -3 -p -r1.6 Scorer.java
--- Scorer.java	17 Aug 2004 20:38:45 -0000	1.6
+++ Scorer.java	21 Sep 2004 19:01:29 -0000
@@ -19,9 +19,9 @@ package org.apache.lucene.search;
 import java.io.IOException;
 
 /** Expert: Common scoring functionality for different types of queries.
- * <br>A <code>Scorer</code> iterates over all documents matching a query,
+ * <br>A <code>Scorer</code> either iterates over documents matching a query,
  * or provides an explanation of the score for a query for a given document.
- * <br>Scores are computed using a given <code>Similarity</code> implementation.
+ * <br>Document scores are computed using a given <code>Similarity</code> implementation.
  */
 public abstract class Scorer {
   private Similarity similarity;
@@ -41,6 +41,7 @@ public abstract class Scorer {
   /** Scores and collects all matching documents.
    * @param hc The collector to which all matching documents are passed through
    * {@link HitCollector#collect(int, float)}.
+   * <br>When this method is used the {@link #explain(int)} method should not be used.
    */
   public void score(HitCollector hc) throws IOException {
     while (next()) {
@@ -50,6 +51,7 @@ public abstract class Scorer {
 
   /** Advances to the next document matching the query.
    * @return true iff there is another document matching the query.
+   * <br>When this method is used the {@link #explain(int)} method should not be used.
    */
   public abstract boolean next() throws IOException;
 
@@ -64,7 +66,8 @@ public abstract class Scorer {
   public abstract float score() throws IOException;
 
   /** Skips to the first match beyond the current whose document number is
-   * greater than or equal to a given target. 
+   * greater than or equal to a given target.
+   * <br>When this method is used the {@link #explain(int)} method should not be used.
    * @param target The target document number.
    * @return true iff there is such a match.
    * <p>Behaves as if written: <pre>
@@ -75,14 +78,13 @@ public abstract class Scorer {
    *     } while (target > doc());
    *     return true;
    *   }
-   * </pre>
-   * Most implementations are considerably more efficient than that.
+   * </pre>Most implementations are considerably more efficient than that.
    */
   public abstract boolean skipTo(int target) throws IOException;
 
   /** Returns an explanation of the score for a document.
-   * <br>When this method is used, the {@link #next()} method
-   * and the {@link #score(HitCollector)} method should not be used.
+   * <br>When this method is used, the {@link #next()}, {@link #skipTo(int)} and
+   * {@link #score(HitCollector)} methods should not be used.
    * @param doc The document number for the explanation.
    */
   public abstract Explanation explain(int doc) throws IOException;