LUCENE-3902: minor javadocs cleanups/nitpicks/formatting and visibility issues

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

lucene/core/src/java/org/apache/lucene/codecs/BlockTreeTermsWriter.java

@@ -69,20 +69,19 @@ import org.apache.lucene.util.fst.Util;
       suffix, and 2) bulk-encode this array using bulk int[]
       codecs; then at search time we can binary search when
       we seek a particular term.
+*/
 
 /**
+ * block-based terms index and dictionary writer.
+ * <p>
  * Writes terms dict and index, block-encoding (column
  * stride) each term's metadata for each set of terms
  * between two index terms.
  *
+ * @see BlockTreeTermsReader
  * @lucene.experimental
  */
 
-/** See {@link BlockTreeTermsReader}.
- *
- * @lucene.experimental
-*/
-
 public class BlockTreeTermsWriter extends FieldsConsumer {
 
   public final static int DEFAULT_MIN_BLOCK_SIZE = 25;

lucene/core/src/java/org/apache/lucene/codecs/intblock/VariableIntBlockIndexInput.java

@@ -73,7 +73,7 @@ public abstract class VariableIntBlockIndexInput extends IntIndexInput {
     public void seek(long pos) throws IOException;
   }
 
-  public static class Reader extends IntIndexInput.Reader {
+  private static class Reader extends IntIndexInput.Reader {
     private final IndexInput in;
 
     public final int[] pending;

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

@@ -35,14 +35,14 @@ import org.apache.lucene.util.BytesRef;
 import org.apache.lucene.index.FieldInvertState; // javadocs
 
 /**
- * Expert: directly creata a field for a document.  Most
+ * Expert: directly create a field for a document.  Most
  * users should use one of the sugar subclasses: {@link
  * IntField}, {@link LongField}, {@link FloatField}, {@link
  * DoubleField}, {@link DocValuesField}, {@link
  * StringField}, {@link TextField}, {@link StoredField}.
  *
  * <p/> A field is a section of a Document. Each field has three
- * parts: name, type andvalue. Values may be text
+ * parts: name, type and value. Values may be text
  * (String, Reader or pre-analyzed TokenStream), binary
  * (byte[]), or numeric (a Number).  Fields are optionally stored in the
  * index, so that they may be returned with hits on the document.

lucene/core/src/java/org/apache/lucene/document/FieldType.java

@@ -23,6 +23,9 @@ import org.apache.lucene.index.IndexableFieldType;
 import org.apache.lucene.search.NumericRangeQuery; // javadocs
 import org.apache.lucene.util.NumericUtils;
 
+/**
+ * Describes the properties of a field.
+ */
 public class FieldType implements IndexableFieldType {
 
   /** Data type of the numeric value

lucene/core/src/java/org/apache/lucene/index/CheckIndex.java

@@ -134,8 +134,7 @@ public class CheckIndex {
     /** Holds the status of each segment in the index.
      *  See {@link #segmentInfos}.
      *
-     * <p><b>WARNING</b>: this API is new and experimental and is
-     * subject to suddenly change in the next release.
+     * @lucene.experimental
      */
     public static class SegmentInfoStatus {
       /** Name of the segment. */
@@ -272,6 +271,9 @@ public class CheckIndex {
       public Throwable error = null;
     }
     
+    /**
+     * Status from testing DocValues
+     */
     public static final class DocValuesStatus {
       /** Number of documents tested. */
       public int docCount;

lucene/core/src/java/org/apache/lucene/index/IndexWriterConfig.java

@@ -51,15 +51,25 @@ import org.apache.lucene.util.Version;
 public final class IndexWriterConfig implements Cloneable {
 
   /**
-   * Specifies the open mode for {@link IndexWriter}:
-   * <ul>
-   * {@link #CREATE} - creates a new index or overwrites an existing one.
-   * {@link #CREATE_OR_APPEND} - creates a new index if one does not exist,
-   * otherwise it opens the index and documents will be appended.
-   * {@link #APPEND} - opens an existing index.
-   * </ul>
+   * Specifies the open mode for {@link IndexWriter}.
    */
-  public static enum OpenMode { CREATE, APPEND, CREATE_OR_APPEND }
+  public static enum OpenMode {
+    /** 
+     * Creates a new index or overwrites an existing one. 
+     */
+    CREATE,
+    
+    /** 
+     * Opens an existing index. 
+     */
+    APPEND,
+    
+    /** 
+     * Creates a new index if one does not exist,
+     * otherwise it opens the index and documents will be appended. 
+     */
+    CREATE_OR_APPEND 
+  }
 
   /** Default value is 32. Change using {@link #setTermIndexInterval(int)}. */
   public static final int DEFAULT_TERM_INDEX_INTERVAL = 32; // TODO: this should be private to the codec, not settable here

lucene/core/src/java/org/apache/lucene/index/IndexableFieldType.java

@@ -19,7 +19,10 @@ package org.apache.lucene.index;
 
 import org.apache.lucene.index.FieldInfo.IndexOptions;
 
-/** @lucene.experimental */
+/** 
+ * Describes the properties of a field.
+ * @lucene.experimental 
+ */
 public interface IndexableFieldType {
 
   /** True if this field should be indexed (inverted) */

lucene/core/src/java/org/apache/lucene/index/MultiTermsEnum.java

@@ -52,7 +52,7 @@ public final class MultiTermsEnum extends TermsEnum {
   private BytesRef current;
   private Comparator<BytesRef> termComp;
 
-  public static class TermsEnumIndex {
+  static class TermsEnumIndex {
     public final static TermsEnumIndex[] EMPTY_ARRAY = new TermsEnumIndex[0];
     final int subIndex;
     final TermsEnum termsEnum;

lucene/core/src/java/org/apache/lucene/index/NormsConsumerPerField.java

@@ -21,7 +21,7 @@ import org.apache.lucene.codecs.DocValuesConsumer;
 import org.apache.lucene.index.DocValues.Type;
 import org.apache.lucene.search.similarities.Similarity;
 
-public class NormsConsumerPerField extends InvertedDocEndConsumerPerField implements Comparable<NormsConsumerPerField> {
+final class NormsConsumerPerField extends InvertedDocEndConsumerPerField implements Comparable<NormsConsumerPerField> {
   private final FieldInfo fieldInfo;
   private final DocumentsWriterPerThread.DocState docState;
   private final Similarity similarity;

lucene/core/src/java/org/apache/lucene/index/SegmentReadState.java

@@ -21,6 +21,7 @@ import org.apache.lucene.store.Directory;
 import org.apache.lucene.store.IOContext;
 
 /**
+ * Holder class for common parameters used during read.
  * @lucene.experimental
  */
 public class SegmentReadState {

lucene/core/src/java/org/apache/lucene/index/StoredFieldVisitor.java

@@ -59,14 +59,24 @@ public abstract class StoredFieldVisitor {
   public void doubleField(FieldInfo fieldInfo, double value) throws IOException {
   }
   
+  /**
+   * Hook before processing a field.
+   * Before a field is processed, this method is invoked so that
+   * subclasses can return a {@link Status} representing whether
+   * they need that particular field or not, or to stop processing
+   * entirely.
+   */
   public abstract Status needsField(FieldInfo fieldInfo) throws IOException;
   
+  /**
+   * Enumeration of possible return values for {@link #needsField}.
+   */
   public static enum Status {
-    /** yes, i want the field */
+    /** YES: the field should be visited. */
     YES,
-    /** no, i do not */
+    /** NO: don't visit this field, but continue processing fields for this document. */
     NO,
-    /** stop loading fields for this document entirely */
+    /** STOP: don't visit this field and stop processing any other fields for this document. */
     STOP
   }
 }

lucene/core/src/java/org/apache/lucene/search/payloads/package.html

@@ -19,19 +19,14 @@
     <TITLE>org.apache.lucene.search.payloads</TITLE>
 </HEAD>
 <BODY>
-<DIV>The payloads package provides Query mechanisms for finding and using payloads.
-
+The payloads package provides Query mechanisms for finding and using payloads.
+<p>
   The following Query implementations are provided:
-</DIV>
-<div>
   <ol>
     <li>{@link org.apache.lucene.search.payloads.PayloadTermQuery PayloadTermQuery} -- Boost a term's score based on the value of the payload located at that term.</li>
   	<li>{@link org.apache.lucene.search.payloads.PayloadNearQuery PayloadNearQuery} -- A {@link org.apache.lucene.search.spans.SpanNearQuery SpanNearQuery} that factors in the value of the payloads located 
   	at each of the positions where the spans occur.</li>
   </ol>
-</div>
-<DIV>&nbsp;</DIV>
-<DIV align="center">
-</DIV>
+</p>
 </BODY>
 </HTML>

lucene/core/src/java/org/apache/lucene/search/similarities/MultiSimilarity.java

@@ -72,7 +72,7 @@ public class MultiSimilarity extends Similarity {
     return new MultiSloppyDocScorer(subScorers);
   }
   
-  public static class MultiExactDocScorer extends ExactSimScorer {
+  static class MultiExactDocScorer extends ExactSimScorer {
     private final ExactSimScorer subScorers[];
     
     MultiExactDocScorer(ExactSimScorer subScorers[]) {
@@ -98,7 +98,7 @@ public class MultiSimilarity extends Similarity {
     }
   }
   
-  public static class MultiSloppyDocScorer extends SloppySimScorer {
+  static class MultiSloppyDocScorer extends SloppySimScorer {
     private final SloppySimScorer subScorers[];
     
     MultiSloppyDocScorer(SloppySimScorer subScorers[]) {
@@ -134,7 +134,7 @@ public class MultiSimilarity extends Similarity {
     }
   }
 
-  public static class MultiStats extends SimWeight {
+  static class MultiStats extends SimWeight {
     final SimWeight subStats[];
     
     MultiStats(SimWeight subStats[]) {

lucene/core/src/java/org/apache/lucene/search/spans/SpanPositionCheckQuery.java

@@ -60,11 +60,22 @@ public abstract class SpanPositionCheckQuery extends SpanQuery implements Clonea
 	    match.extractTerms(terms);
   }
 
-  /** Return value if the match should be accepted {@code YES}, rejected {@code NO},
-   * or rejected and enumeration should advance to the next document {@code NO_AND_ADVANCE}.
-   * @see #acceptPosition(Spans)
+  /** 
+   * Return value for {@link SpanPositionCheckQuery#acceptPosition(Spans)}.
    */
-  protected static enum AcceptStatus { YES, NO, NO_AND_ADVANCE };
+  protected static enum AcceptStatus {
+    /** Indicates the match should be accepted */
+    YES,
+    
+    /** Indicates the match should be rejected */
+    NO,
+    
+    /** 
+     * Indicates the match should be rejected, and the enumeration should advance
+     * to the next document.
+     */
+    NO_AND_ADVANCE 
+  };
   
   /**
    * Implementing classes are required to return whether the current position is a match for the passed in

lucene/core/src/java/org/apache/lucene/util/automaton/ByteRunAutomaton.java

@@ -17,6 +17,9 @@ package org.apache.lucene.util.automaton;
  * limitations under the License.
  */
 
+/**
+ * Automaton representation for matching UTF-8 byte[].
+ */
 public class ByteRunAutomaton extends RunAutomaton {
   
   public ByteRunAutomaton(Automaton a) {

lucene/core/src/java/org/apache/lucene/util/automaton/CharacterRunAutomaton.java

@@ -17,6 +17,9 @@ package org.apache.lucene.util.automaton;
  * limitations under the License.
  */
 
+/**
+ * Automaton representation for matching char[].
+ */
 public class CharacterRunAutomaton extends RunAutomaton {
 
   public CharacterRunAutomaton(Automaton a) {

lucene/core/src/java/org/apache/lucene/util/automaton/UTF32ToUTF8.java

@@ -26,7 +26,10 @@ import java.util.ArrayList;
 // TODO
 //   - do we really need the .bits...?  if not we can make util in UnicodeUtil to convert 1 char into a BytesRef
 
-/** @lucene.internal */
+/** 
+ * Converts UTF-32 automata to the equivalent UTF-8 representation.
+ * @lucene.internal 
+ */
 public final class UTF32ToUTF8 {
 
   // Unicode boundaries for UTF8 bytes 1,2,3,4

lucene/core/src/java/org/apache/lucene/util/fst/Util.java

@@ -497,7 +497,7 @@ public final class Util {
   }
 
   /** Holds a single input (IntsRef) + output, returned by
-   *  {@link #shortestPaths}. */
+   *  {@link #shortestPaths shortestPaths()}. */
   public final static class MinResult<T> implements Comparable<MinResult<T>> {
     public final IntsRef input;
     public final T output;