- Applied patch from http://issues.apache.org/bugzilla/show_bug.cgi?id=30360

PR: 30360
Submitted by:	Paul Elschot
Reviewed by:	Otis Gospodnetic


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

CHANGES.txt

@@ -25,6 +25,9 @@ $Id$
      in case of compound file format has been improved. 
      (Bernhard, Dmitry, and Christoph)
 
+  6. Added javadoc-internal to build.xml - bug #30360
+     (Paul Elschot via Otis)
+ 
 1.4.1
 
  1. Fixed a performance bug in hit sorting code, where values were not

build.xml

@@ -355,6 +355,27 @@
     </javadoc>
   </target>
 
+  <target name="javadocs-internal">
+    <mkdir dir="${build.dir}/docs/api-internal"/>
+    <javadoc
+      sourcepath="src/java"
+      overview="src/java/overview.html"
+      packagenames="org.apache.lucene.*"
+      access="package"
+      destdir="${build.dir}/docs/api-internal"
+      encoding="${build.encoding}"
+      author="true"
+      version="true"
+      use="true"
+      link="${javadoc.link}"
+      windowtitle="${Name} ${version} public and internal API"
+      doctitle="${Name} ${version} public and internal API"
+      bottom="Copyright &amp;copy; ${year} Apache Software Foundation.  All Rights Reserved."
+      >
+      <tag name="todo" description="To Do:"/>
+    </javadoc>
+  </target>
+
   <!-- ================================================================== -->
   <!-- D I S T R I B U T I O N                                            -->
   <!-- ================================================================== -->

src/java/org/apache/lucene/index/CompoundFileReader.java

@@ -203,7 +203,7 @@ class CompoundFileReader extends Directory {
          *  position in the input.
          * @param b the array to read bytes into
          * @param offset the offset in the array to start storing bytes
-         * @param len the number of bytes to read
+         * @param length the number of bytes to read
          */
         protected void readInternal(byte[] b, int offset, int len)
         throws IOException

src/java/org/apache/lucene/index/FieldInfos.java

@@ -46,8 +46,6 @@ final class FieldInfos {
    * @param d The directory to open the InputStream from
    * @param name The name of the file to open the InputStream from in the Directory
    * @throws IOException
-   * 
-   * @see #read
    */
   FieldInfos(Directory d, String name) throws IOException {
     InputStream input = d.openFile(name);

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

@@ -18,11 +18,17 @@ package org.apache.lucene.search;
 
 import java.io.IOException;
 
-/** Expert: Implements scoring for a class of queries. */
+/** Expert: Common scoring functionality for different types of queries.
+ * <br>A <code>Scorer</code> iterates over all 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.
+ */
 public abstract class Scorer {
   private Similarity similarity;
 
-  /** Constructs a Scorer. */
+  /** Constructs a Scorer.
+   * @param similarity The <code>Similarity</code> implementation used by this scorer.
+   */
   protected Scorer(Similarity similarity) {
     this.similarity = similarity;
   }
@@ -32,28 +38,36 @@ public abstract class Scorer {
     return this.similarity;
   }
 
-  /** Scores all documents and passes them to a collector. */
+  /** Scores and collects all matching documents.
+   * @param hc The collector to which all matching documents are passed through
+   * {@link HitCollector#collect(int, float)}.
+   */
   public void score(HitCollector hc) throws IOException {
     while (next()) {
       hc.collect(doc(), score());
     }
   }
 
-  /** Advance to the next document matching the query.  Returns true iff there
+  /** Advances to the next document matching the query.
-   * is another match. */
+   * @return true iff there is another document matching the query.
+   */
   public abstract boolean next() throws IOException;
 
-  /** Returns the current document number.  Initially invalid, until {@link
+  /** Returns the current document number matching the query.
-   * #next()} is called the first time. */
+   * Initially invalid, until {@link #next()} is called the first time.
+   */
   public abstract int doc();
 
-  /** Returns the score of the current document.  Initially invalid, until
+  /** Returns the score of the current document matching the query.
-   * {@link #next()} is called the first time. */
+   * Initially invalid, until {@link #next()} is called the first time.
+   */
   public abstract float score() throws IOException;
 
   /** Skips to the first match beyond the current whose document number is
-   * greater than or equal to <i>target</i>. <p>Returns true iff there is such
+   * greater than or equal to a given target. 
-   * a match.  <p>Behaves as if written: <pre>
+   * @param target The target document number.
+   * @return true iff there is such a match.
+   * <p>Behaves as if written: <pre>
    *   boolean skipTo(int target) {
    *     do {
    *       if (!next())
@@ -66,7 +80,11 @@ public abstract class Scorer {
    */
   public abstract boolean skipTo(int target) throws IOException;
 
-  /** Returns an explanation of the score for <code>doc</code>. */
+  /** 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.
+   * @param doc The document number for the explanation.
+   */
   public abstract Explanation explain(int doc) throws IOException;
 
 }

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

@@ -20,6 +20,8 @@ import java.io.IOException;
 
 import org.apache.lucene.index.TermDocs;
 
+/** Expert: A <code>Scorer</code> for documents matching a <code>Term</code>.
+ */
 final class TermScorer extends Scorer {
   private Weight weight;
   private TermDocs termDocs;
@@ -35,6 +37,12 @@ final class TermScorer extends Scorer {
   private static final int SCORE_CACHE_SIZE = 32;
   private float[] scoreCache = new float[SCORE_CACHE_SIZE];
 
+  /** Construct a <code>TermScorer</code>.
+   * @param weight The weight of the <code>Term</code> in the query.
+   * @param td An iterator over the documents matching the <code>Term</code>.
+   * @param similarity The </code>Similarity</code> implementation to be used for score computations.
+   * @param norms The field norms of the document fields for the <code>Term</code>.
+   */
   TermScorer(Weight weight, TermDocs td, Similarity similarity,
              byte[] norms) {
     super(similarity);
@@ -47,8 +55,16 @@ final class TermScorer extends Scorer {
       scoreCache[i] = getSimilarity().tf(i) * weightValue;
   }
 
+  /** Returns the current document number matching the query.
+   * Initially invalid, until {@link #next()} is called the first time.
+   */
   public int doc() { return doc; }
 
+  /** Advances to the next document matching the query.
+   * <br>The iterator over the matching documents is buffered using
+   * {@link TermDocs#read(int[],int[])}.
+   * @return true iff there is another document matching the query.
+   */
   public boolean next() throws IOException {
     pointer++;
     if (pointer >= pointerMax) {
@@ -75,6 +91,12 @@ final class TermScorer extends Scorer {
     return raw * Similarity.decodeNorm(norms[doc]); // normalize for field
   }
 
+  /** Skips to the first match beyond the current whose document number is
+   * greater than or equal to a given target. 
+   * <br>The implementation uses {@link TermDocs#skipTo(int)}.
+   * @param target The target document number.
+   * @return true iff there is such a match.
+   */
   public boolean skipTo(int target) throws IOException {
     // first scan in cache
     for (pointer++; pointer < pointerMax; pointer++) {
@@ -97,6 +119,12 @@ final class TermScorer extends Scorer {
     return result;
   }
 
+  /** 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.
+   * @param doc The document number for the explanation.
+   * @todo Modify to make use of {@link TermDocs#skipTo(int)}.
+   */
   public Explanation explain(int doc) throws IOException {
     TermQuery query = (TermQuery)weight.getQuery();
     Explanation tfExplanation = new Explanation();
@@ -120,6 +148,6 @@ final class TermScorer extends Scorer {
     return tfExplanation;
   }
 
+  /** Returns a string representation of this <code>TermScorer</code>. */
   public String toString() { return "scorer(" + weight + ")"; }
-
 }

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

@@ -25,7 +25,7 @@ import org.apache.lucene.index.IndexReader;
  * <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
+ * 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)}.
  */