javadocs

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

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

@@ -51,6 +51,7 @@ import org.apache.lucene.store.Directory;
 public abstract class DirectoryReader extends BaseCompositeReader<AtomicReader> {
   public static final int DEFAULT_TERMS_INDEX_DIVISOR = 1;
 
+  /** The index directory. */
   protected final Directory directory;
   
   /** Returns a IndexReader reading the index in the given

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

@@ -31,7 +31,9 @@ import org.apache.lucene.index.DocValues.Type;
  **/
 
 public final class FieldInfo {
+  /** Field's name */
   public final String name;
+  /** Internal field number */
   public final int number;
 
   private boolean indexed;
@@ -164,27 +166,27 @@ public final class FieldInfo {
     assert checkConsistency();
   }
   
-  /** @return IndexOptions for the field, or null if the field is not indexed */
+  /** Returns IndexOptions for the field, or null if the field is not indexed */
   public IndexOptions getIndexOptions() {
     return indexOptions;
   }
   
   /**
-   * @return true if this field has any docValues.
+   * Returns true if this field has any docValues.
    */
   public boolean hasDocValues() {
     return docValueType != null;
   }
 
   /**
-   * @return {@link DocValues.Type} of the docValues. this may be null if the field has no docvalues.
+   * Returns {@link DocValues.Type} of the docValues. this may be null if the field has no docvalues.
    */
   public DocValues.Type getDocValuesType() {
     return docValueType;
   }
   
   /**
-   * @return {@link DocValues.Type} of the norm. this may be null if the field has no norms.
+   * Returns {@link DocValues.Type} of the norm. this may be null if the field has no norms.
    */
   public DocValues.Type getNormType() {
     return normType;
@@ -208,35 +210,35 @@ public final class FieldInfo {
   }
   
   /**
-   * @return true if norms are explicitly omitted for this field
+   * Returns true if norms are explicitly omitted for this field
    */
   public boolean omitsNorms() {
     return omitNorms;
   }
   
   /**
-   * @return true if this field actually has any norms.
+   * Returns true if this field actually has any norms.
    */
   public boolean hasNorms() {
     return normType != null;
   }
   
   /**
-   * @return true if this field is indexed.
+   * Returns true if this field is indexed.
    */
   public boolean isIndexed() {
     return indexed;
   }
   
   /**
-   * @return true if any payloads exist for this field.
+   * Returns true if any payloads exist for this field.
    */
   public boolean hasPayloads() {
     return storePayloads;
   }
   
   /**
-   * @return true if any term vectors exist for this field.
+   * Returns true if any term vectors exist for this field.
    */
   public boolean hasVectors() {
     return storeTermVector;
@@ -271,7 +273,7 @@ public final class FieldInfo {
   }
   
   /**
-   * @return internal codec attributes map. May be null if no mappings exist.
+   * Returns internal codec attributes map. May be null if no mappings exist.
    */
   public Map<String,String> attributes() {
     return attributes;

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

@@ -44,6 +44,9 @@ public class FieldInfos implements Iterable<FieldInfo> {
   private final HashMap<String,FieldInfo> byName = new HashMap<String,FieldInfo>();
   private final Collection<FieldInfo> values; // for an unmodifiable iterator
   
+  /**
+   * Constructs a new FieldInfos from an array of FieldInfo objects
+   */
   public FieldInfos(FieldInfo[] infos) {
     boolean hasVectors = false;
     boolean hasProx = false;
@@ -98,30 +101,22 @@ public class FieldInfos implements Iterable<FieldInfo> {
     return hasOffsets;
   }
   
-  /**
-   * @return true if at least one field has any vectors
-   */
+  /** Returns true if any fields have vectors */
   public boolean hasVectors() {
     return hasVectors;
   }
   
-  /**
-   * @return true if at least one field has any norms
-   */
+  /** Returns true if any fields have norms */
   public boolean hasNorms() {
     return hasNorms;
   }
   
-  /**
-   * @return true if at least one field has doc values
-   */
+  /** Returns true if any fields have DocValues */
   public boolean hasDocValues() {
     return hasDocValues;
   }
   
-  /**
-   * @return number of fields
-   */
+  /** Returns the number of fields */
   public int size() {
     assert byNumber.size() == byName.size();
     return byNumber.size();

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

@@ -40,8 +40,13 @@ public class FilterAtomicReader extends AtomicReader {
   /** Base class for filtering {@link Fields}
    *  implementations. */
   public static class FilterFields extends Fields {
+    /** The underlying Fields instance. */
     protected final Fields in;
 
+    /**
+     * Creates a new FilterFields.
+     * @param in the underlying Fields instance.
+     */
     public FilterFields(Fields in) {
       this.in = in;
     }
@@ -65,8 +70,13 @@ public class FilterAtomicReader extends AtomicReader {
   /** Base class for filtering {@link Terms}
    *  implementations. */
   public static class FilterTerms extends Terms {
+    /** The underlying Terms instance. */
     protected final Terms in;
 
+    /**
+     * Creates a new FilterTerms
+     * @param in the underlying Terms instance.
+     */
     public FilterTerms(Terms in) {
       this.in = in;
     }
@@ -124,8 +134,13 @@ public class FilterAtomicReader extends AtomicReader {
 
   /** Base class for filtering {@link TermsEnum} implementations. */
   public static class FilterTermsEnum extends TermsEnum {
+    /** The underlying TermsEnum instance. */
     protected final TermsEnum in;
 
+    /**
+     * Creates a new FilterTermsEnum
+     * @param in the underlying TermsEnum instance.
+     */
     public FilterTermsEnum(TermsEnum in) { this.in = in; }
 
     @Override
@@ -201,8 +216,13 @@ public class FilterAtomicReader extends AtomicReader {
 
   /** Base class for filtering {@link DocsEnum} implementations. */
   public static class FilterDocsEnum extends DocsEnum {
+    /** The underlying DocsEnum instance. */
     protected final DocsEnum in;
 
+    /**
+     * Create a new FilterDocsEnum
+     * @param in the underlying DocsEnum instance.
+     */
     public FilterDocsEnum(DocsEnum in) {
       this.in = in;
     }
@@ -235,8 +255,13 @@ public class FilterAtomicReader extends AtomicReader {
 
   /** Base class for filtering {@link DocsAndPositionsEnum} implementations. */
   public static class FilterDocsAndPositionsEnum extends DocsAndPositionsEnum {
+    /** The underlying DocsAndPositionsEnum instance. */
     protected final DocsAndPositionsEnum in;
 
+    /**
+     * Create a new FilterDocsAndPositionsEnum
+     * @param in the underlying DocsAndPositionsEnum instance.
+     */
     public FilterDocsAndPositionsEnum(DocsAndPositionsEnum in) {
       this.in = in;
     }
@@ -287,6 +312,7 @@ public class FilterAtomicReader extends AtomicReader {
     }
   }
 
+  /** The underlying AtomicReader. */
   protected final AtomicReader in;
 
   /**

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

@@ -48,7 +48,20 @@ public abstract class FilteredTermsEnum extends TermsEnum {
    * the enum should call {@link #nextSeekTerm} and step forward.
    * @see #accept(BytesRef)
    */
-  protected static enum AcceptStatus {YES, YES_AND_SEEK, NO, NO_AND_SEEK, END};
+  protected static enum AcceptStatus {
+    /** Accept the term and position the enum at the next term. */
+    YES, 
+    /** Accept the term and advance ({@link FilteredTermsEnum#nextSeekTerm(BytesRef)})
+     * to the next term. */
+    YES_AND_SEEK, 
+    /** Reject the term and position the enum at the next term. */
+    NO, 
+    /** Reject the term and advance ({@link FilteredTermsEnum#nextSeekTerm(BytesRef)})
+     * to the next term. */
+    NO_AND_SEEK, 
+    /** Reject the term and stop enumerating. */
+    END
+  };
   
   /** Return if term is accepted, not accepted or the iteration should ended
    * (and possibly seek).

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

@@ -187,6 +187,10 @@ public final class IndexFileNames {
     return filename;
   }
   
+  /**
+   * Removes the extension (anything after the first '.'),
+   * otherwise returns the original filename.
+   */
   public static String stripExtension(String filename) {
     int idx = filename.indexOf('.');
     if (idx != -1) {

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

@@ -243,7 +243,8 @@ public abstract class IndexReader implements Closeable {
   }
   
   /**
-   * @throws AlreadyClosedException if this IndexReader is closed
+   * Throws AlreadyClosedException if this IndexReader or any
+   * of its child readers is closed, otherwise returns.
    */
   protected final void ensureOpen() throws AlreadyClosedException {
     if (refCount.get() <= 0) {

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

@@ -549,6 +549,14 @@ public class IndexWriter implements Closeable, TwoPhaseCommit {
     }
   }
 
+  /**
+   * Used internally to throw an {@link
+   * AlreadyClosedException} if this IndexWriter has been
+   * closed.
+   * <p>
+   * Calls {@link #ensureOpen(boolean) ensureOpen(true)}.
+   * @throws AlreadyClosedException if this IndexWriter is closed
+   */
   protected final void ensureOpen() throws AlreadyClosedException {
     ensureOpen(true);
   }
@@ -1030,6 +1038,9 @@ public class IndexWriter implements Closeable, TwoPhaseCommit {
     return count;
   }
 
+  /**
+   * Returns true if this index has deletions (including buffered deletions).
+   */
   public synchronized boolean hasDeletions() {
     ensureOpen();
     if (bufferedDeletesStream.any()) {

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

@@ -89,6 +89,15 @@ public final class MultiFields extends Fields {
     }
   }
 
+  /** Returns a single {@link Bits} instance for this
+   *  reader, merging live Documents on the
+   *  fly.  This method will return null if the reader 
+   *  has no deletions.
+   *
+   *  <p><b>NOTE</b>: this is a very slow way to access live docs.
+   *  For example, each Bits access will require a binary search.
+   *  It's better to get the sub-readers and iterate through them
+   *  yourself. */
   public static Bits getLiveDocs(IndexReader reader) {
     if (reader.hasDeletions()) {
       final List<AtomicReaderContext> leaves = reader.leaves();
@@ -176,6 +185,11 @@ public final class MultiFields extends Fields {
     return null;
   }
 
+  /**
+   * Expert: construct a new MultiFields instance directly.
+   * @lucene.internal
+   */
+  // TODO: why is this public?
   public MultiFields(Fields[] subs, ReaderSlice[] subSlices) {
     this.subs = subs;
     this.subSlices = subSlices;
@@ -229,6 +243,14 @@ public final class MultiFields extends Fields {
     return -1;
   }
 
+  /** Returns the total number of occurrences of this term
+   *  across all documents (the sum of the freq() for each
+   *  doc that has this term).  This will be -1 if the
+   *  codec doesn't support this measure.  Note that, like
+   *  other term measures, this measure does not take
+   *  deleted documents into account.
+   * @see TermsEnum#totalTermFreq()
+   */
   public static long totalTermFreq(IndexReader r, String field, BytesRef text) throws IOException {
     final Terms terms = getTerms(r, field);
     if (terms != null) {
@@ -256,6 +278,14 @@ public final class MultiFields extends Fields {
     return builder.finish();
   }
 
+  /** Call this to get the (merged) FieldInfos representing the
+   *  set of indexed fields <b>only</b> for a composite reader. 
+   *  <p>
+   *  NOTE: the returned field numbers will likely not
+   *  correspond to the actual field numbers in the underlying
+   *  readers, and codec metadata ({@link FieldInfo#getAttribute(String)}
+   *  will be unavailable.
+   */
   public static Collection<String> getIndexedFields(IndexReader reader) {
     final Collection<String> fields = new HashSet<String>();
     for(final FieldInfo fieldInfo : getMergedFieldInfos(reader)) {

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

@@ -97,15 +97,25 @@ public class SegmentInfoPerCommit {
     sizeInBytes =  -1;
   }
 
+  /**
+   * Sets the generation number of the live docs file.
+   * @see #getDelGen()
+   */
   public void setDelGen(long delGen) {
     this.delGen = delGen;
     sizeInBytes =  -1;
   }
 
+  /** Returns true if there are any deletions for the 
+   * segment at this commit. */
   public boolean hasDeletions() {
     return delGen != -1;
   }
 
+  /**
+   * Returns the next available generation number
+   * of the live docs file.
+   */
   public long getNextDelGen() {
     if (delGen == -1) {
       return 1;
@@ -114,10 +124,17 @@ public class SegmentInfoPerCommit {
     }
   }
 
+  /**
+   * Returns generation number of the live docs file 
+   * or -1 if there are no deletes yet.
+   */
   public long getDelGen() {
     return delGen;
   }
   
+  /**
+   * Returns the number of deleted docs in the segment.
+   */
   public int getDelCount() {
     return delCount;
   }

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

@@ -47,9 +47,11 @@ public final class SegmentReader extends AtomicReader {
   final SegmentCoreReaders core;
 
   /**
+   * Constructs a new SegmentReader with a new core.
    * @throws CorruptIndexException if the index is corrupt
    * @throws IOException if there is a low-level IO error
    */
+  // TODO: why is this public?
   public SegmentReader(SegmentInfoPerCommit si, int termInfosIndexDivisor, IOContext context) throws IOException {
     this.si = si;
     core = new SegmentCoreReaders(this, si.info.dir, si, context, termInfosIndexDivisor);
@@ -76,19 +78,19 @@ public final class SegmentReader extends AtomicReader {
     }
   }
 
-  // Create new SegmentReader sharing core from a previous
-  // SegmentReader and loading new live docs from a new
-  // deletes file.  Used by openIfChanged.
+  /** Create new SegmentReader sharing core from a previous
+   *  SegmentReader and loading new live docs from a new
+   *  deletes file.  Used by openIfChanged. */
   SegmentReader(SegmentInfoPerCommit si, SegmentCoreReaders core, IOContext context) throws IOException {
     this(si, core,
          si.info.getCodec().liveDocsFormat().readLiveDocs(si.info.dir, si, context),
          si.info.getDocCount() - si.getDelCount());
   }
 
-  // Create new SegmentReader sharing core from a previous
-  // SegmentReader and using the provided in-memory
-  // liveDocs.  Used by IndexWriter to provide a new NRT
-  // reader:
+  /** Create new SegmentReader sharing core from a previous
+   *  SegmentReader and using the provided in-memory
+   *  liveDocs.  Used by IndexWriter to provide a new NRT
+   *  reader */
   SegmentReader(SegmentInfoPerCommit si, SegmentCoreReaders core, Bits liveDocs, int numDocs) {
     this.si = si;
     this.core = core;

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

@@ -132,8 +132,4 @@ public final class Term implements Comparable<Term> {
 
   @Override
   public final String toString() { return field + ":" + bytes.utf8ToString(); }
-
-  public Term deepCopyOf() {
-    return new Term(field, BytesRef.deepCopyOf(bytes));
-  }
 }

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

@@ -51,12 +51,15 @@ public abstract class TermsEnum implements BytesRefIterator {
     return atts;
   }
   
-  /** Represents returned result from {@link #seekCeil}.
-   *  If status is FOUND, then the precise term was found.
-   *  If status is NOT_FOUND, then a different term was
-   *  found.  If the status is END, the end of the iteration
-   *  was hit. */
-  public static enum SeekStatus {END, FOUND, NOT_FOUND};
+  /** Represents returned result from {@link #seekCeil}. */
+  public static enum SeekStatus {
+    /** The term was not found, and the end of iteration was hit. */
+    END,
+    /** The precise term was found. */
+    FOUND,
+    /** A different term was found after the requested term */
+    NOT_FOUND
+  };
 
   /** Attempts to seek to the exact term, returning
    *  true if the term is found.  If this returns false, the

lucene/core/src/java/org/apache/lucene/util/IOUtils.java

@@ -98,7 +98,9 @@ public final class IOUtils {
     }
   }
 
-  /** @see #closeWhileHandlingException(Exception, Closeable...) */
+  /**
+   * Closes all given <tt>Closeable</tt>s, suppressing all thrown exceptions. 
+   * @see #closeWhileHandlingException(Exception, Closeable...) */
   public static <E extends Exception> void closeWhileHandlingException(E priorException, Iterable<? extends Closeable> objects) throws E, IOException {
     Throwable th = null;
 
@@ -160,6 +162,7 @@ public final class IOUtils {
   }
   
   /**
+   * Closes all given <tt>Closeable</tt>s.
    * @see #close(Closeable...)
    */
   public static void close(Iterable<? extends Closeable> objects) throws IOException {
@@ -205,6 +208,7 @@ public final class IOUtils {
   }
   
   /**
+   * Closes all given <tt>Closeable</tt>s, suppressing all thrown exceptions.
    * @see #closeWhileHandlingException(Closeable...)
    */
   public static void closeWhileHandlingException(Iterable<? extends Closeable> objects) {
@@ -322,6 +326,11 @@ public final class IOUtils {
     }
   }
   
+  /**
+   * Deletes all given files, suppressing all thrown IOExceptions.
+   * <p>
+   * Note that the files should not be null.
+   */
   public static void deleteFilesIgnoringExceptions(Directory dir, String... files) {
     for (String name : files) {
       try {