some javadoc comment improvements

PR: 31350
Submitted by: Paul Elschot


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

src/java/org/apache/lucene/document/Field.java

@@ -246,8 +246,9 @@ public final class Field implements Serializable {
     return f;
   }
   
-  /** The name of the field (e.g., "date", "title", "body", ...)
-    as an interned string. */
+  /** Returns the name of the field as an interned string.
+   * For example "date", "title", "body", ...
+   */
   public String name()    { return name; }
 
   /** The value of the field as a String, or null.  If null, the Reader value

src/java/org/apache/lucene/queryParser/QueryParser.jj

@@ -496,7 +496,7 @@ public class QueryParser {
 
   /**
    * Returns a String where those characters that QueryParser
-   * expects to be escaped are escaped, i.e. preceded by a <code>\</code>.
+   * expects to be escaped are escaped by a preceding <code>\</code>.
    */
   public static String escape(String s) {
     StringBuffer sb = new StringBuffer();

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

@@ -86,7 +86,7 @@ public final class FuzzyQuery extends MultiTermQuery {
   }
     
   /**
-   * Returns the prefix length, i.e. the number of characters at the start
+   * Returns the non-fuzzy prefix length. This is the number of characters at the start
    * of a term that must be identical (not fuzzy) to the query term if the query
    * is to match that term. 
    */

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

@@ -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()) {
@@ -67,6 +68,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;
 
@@ -81,7 +83,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>
@@ -92,14 +95,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;

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

@@ -99,7 +99,7 @@ public abstract class Similarity {
    * @see #encodeNorm(float)
    */
   public static float decodeNorm(byte b) {
-    return NORM_TABLE[b & 0xFF];
+    return NORM_TABLE[b & 0xFF];  // & 0xFF maps negative bytes to positive above 127
   }
 
   /** Returns a table for decoding normalization bytes.

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

@@ -21,13 +21,18 @@ import java.io.IOException;
 import org.apache.lucene.index.IndexReader;
 
 /** Expert: Calculate query weights and build query scorers.
- *
- * <p>A Weight is constructed by a query, given a Searcher ({@link
- * Query#createWeight(Searcher)}).  The {@link #sumOfSquaredWeights()} method
- * is then called on the top-level query to compute the query normalization
- * factor {@link Similarity#queryNorm(float)}.  This factor is then passed to
- * {@link #normalize(float)}.  At this point the weighting is complete and a
- * scorer may be constructed by calling {@link #scorer(IndexReader)}.
+ * <br>A <code>Weight</code> is used in the following way:
+ * <ol>
+ * <li>A <code>Weight</code> is constructed by a top-level query,
+ *     given a <code>Searcher</code> ({@link Query#createWeight(Searcher)}).
+ * <li>The {@link #sumOfSquaredWeights()} method is called
+ *     on the <code>Weight</code> to compute
+ *     the query normalization factor {@link Similarity#queryNorm(float)}
+ *     of the query clauses contained in the query.
+ * <li>The query normalization factor is passed to {@link #normalize(float)}.
+ *     At this point the weighting is complete.
+ * <li>A <code>Scorer</code> is constructed by {@link #scorer(IndexReader)}.
+ * </ol>
  */
 public interface Weight extends java.io.Serializable {
   /** The query that this concerns. */