added some javadoc

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

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

@@ -144,7 +144,7 @@ final class DocFieldProcessor extends DocConsumer {
       try {
         consumer.close();  
       } catch (IOException e) {
-        // nocommit handle exce
+        // ignore and continue closing remaining consumers
       }
     }
     perDocConsumers.clear();

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

@@ -1069,7 +1069,19 @@ public abstract class IndexReader implements Cloneable,Closeable {
    * through them yourself. */
   public abstract Fields fields() throws IOException;
   
-  // nocommit javadoc
+  /**
+   * Flex API: returns {@link PerDocValues} for this reader.
+   *  This method may return null if the reader has no per-document
+   *  values stored.
+   *
+   * <p><b>NOTE</b>: if this is a multi reader ({@link
+   * #getSequentialSubReaders} is not null) then this
+   * method will throw UnsupportedOperationException.  If
+   * you really need {@link PerDocValues} for such a reader,
+   * use {@link MultiPerDocValues#getPerDocs(IndexReader)}.  However, for
+   * performance reasons, it's best to get all sub-readers
+   * using {@link ReaderUtil#gatherSubReaders} and iterate
+   * through them yourself. */
   public abstract PerDocValues perDocValues() throws IOException;
 
   public int docFreq(Term term) throws IOException {

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

@@ -29,11 +29,20 @@ import org.apache.lucene.index.values.MultiDocValues;
 import org.apache.lucene.index.values.Type;
 import org.apache.lucene.index.values.MultiDocValues.DocValuesIndex;
 import org.apache.lucene.util.ReaderUtil;
+import org.apache.lucene.util.ReaderUtil.Gather;
 
 /**
+ * Exposes per-document flex API, merged from per-document flex API of
+ * sub-segments. This is useful when you're interacting with an
+ * {@link IndexReader} implementation that consists of sequential sub-readers
+ * (eg DirectoryReader or {@link MultiReader}).
  * 
- * nocommit - javadoc
- * @experimental
+ * <p>
+ * <b>NOTE</b>: for multi readers, you'll get better performance by gathering
+ * the sub readers using {@link ReaderUtil#gatherSubReaders} and then operate
+ * per-reader, instead of using this class.
+ * 
+ * @lucene.experimental
  */
 public class MultiPerDocValues extends PerDocValues {
   private final PerDocValues[] subs;
@@ -50,6 +59,14 @@ public class MultiPerDocValues extends PerDocValues {
     }
   }
 
+  /**
+   * Returns a single {@link PerDocValues} instance for this reader, merging
+   * their values on the fly. This method will not return <code>null</code>.
+   * 
+   * <p>
+   * <b>NOTE</b>: this is a slow way to access postings. It's better to get the
+   * sub-readers (using {@link Gather}) and iterate through them yourself.
+   */
   public static PerDocValues getPerDocs(IndexReader r) throws IOException {
     final IndexReader[] subs = r.getSequentialSubReaders();
     if (subs == null) {

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

@@ -18,10 +18,13 @@ package org.apache.lucene.index;
 import java.io.PrintStream;
 import java.util.concurrent.atomic.AtomicLong;
 
+import org.apache.lucene.index.codecs.PerDocConsumer;
 import org.apache.lucene.store.Directory;
 
 /**
- * nocommit - javadoc
+ * Encapsulates all necessary state to initiate a {@link PerDocConsumer} and
+ * create all necessary files in order to consume and merge per-document values.
+ * 
  * @lucene.experimental
  */
 public class PerDocWriteState {
@@ -33,14 +36,9 @@ public class PerDocWriteState {
   public final SegmentCodecs segmentCodecs;
   public final int codecId;
 
-  /** Expert: The fraction of terms in the "dictionary" which should be stored
-   * in RAM.  Smaller values use more memory, but make searching slightly
-   * faster, while larger values use less memory and make searching slightly
-   * slower.  Searching is typically not dominated by dictionary lookup, so
-   * tweaking this is rarely useful.*/
-  public int termIndexInterval;                   // TODO: this should be private to the codec, not settable here or in IWC
-
-  public PerDocWriteState(PrintStream infoStream, Directory directory, String segmentName, FieldInfos fieldInfos, AtomicLong bytesUsed, int codecId) {
+  PerDocWriteState(PrintStream infoStream, Directory directory,
+      String segmentName, FieldInfos fieldInfos, AtomicLong bytesUsed,
+      int codecId) {
     this.infoStream = infoStream;
     this.directory = directory;
     this.segmentName = segmentName;
@@ -49,8 +47,8 @@ public class PerDocWriteState {
     this.codecId = codecId;
     this.bytesUsed = bytesUsed;
   }
-  
-  public PerDocWriteState(SegmentWriteState state) {
+
+  PerDocWriteState(SegmentWriteState state) {
     infoStream = state.infoStream;
     directory = state.directory;
     segmentCodecs = state.segmentCodecs;
@@ -59,8 +57,8 @@ public class PerDocWriteState {
     codecId = state.codecId;
     bytesUsed = new AtomicLong(0);
   }
-  
-  public PerDocWriteState(PerDocWriteState state, int codecId) {
+
+  PerDocWriteState(PerDocWriteState state, int codecId) {
     this.infoStream = state.infoStream;
     this.directory = state.directory;
     this.segmentName = state.segmentName;
@@ -69,8 +67,7 @@ public class PerDocWriteState {
     this.codecId = codecId;
     this.bytesUsed = state.bytesUsed;
   }
-  
-  
+
   public String codecIdAsString() {
     return "" + codecId;
   }

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

@@ -18,7 +18,6 @@ package org.apache.lucene.index;
  */
 
 import java.io.PrintStream;
-import java.util.concurrent.atomic.AtomicLong;
 
 import org.apache.lucene.store.Directory;
 import org.apache.lucene.util.BitVector;

lucene/src/java/org/apache/lucene/index/codecs/FieldsProducer.java

@@ -23,7 +23,6 @@ import java.io.IOException;
 import org.apache.lucene.index.Fields;
 import org.apache.lucene.index.FieldsEnum;
 import org.apache.lucene.index.Terms;
-import org.apache.lucene.index.values.DocValues;
 
 /** Abstract API that consumes terms, doc, freq, prox and
  *  payloads postings.  Concrete implementations of this

lucene/src/java/org/apache/lucene/index/codecs/PerDocConsumer.java

@@ -22,15 +22,24 @@ import org.apache.lucene.index.FieldInfo;
 import org.apache.lucene.index.values.DocValues;
 
 /**
- * nocommit - javadoc
- * @experimental
- *
+ * Abstract API that consumes per document values. Concrete implementations of
+ * this convert field values into a Codec specific format during indexing.
+ * <p>
+ * The {@link PerDocConsumer} API is accessible through flexible indexing / the
+ * {@link Codec} - API providing per field consumers and producers for inverted
+ * data (terms, postings) as well as per-document data.
+ * 
+ * @lucene.experimental
  */
 public abstract class PerDocConsumer implements Closeable{
   /** Adds a new DocValuesField */
   public abstract DocValuesConsumer addValuesField(FieldInfo field)
       throws IOException;
 
+  /**
+   * Consumes and merges the given {@link PerDocValues} producer
+   * into this consumers format.   
+   */
   public void merge(MergeState mergeState, PerDocValues producer)
       throws IOException {
     Iterable<String> fields = producer.fields();

lucene/src/java/org/apache/lucene/index/codecs/PerDocValues.java

@@ -22,9 +22,16 @@ import java.util.Collection;
 import org.apache.lucene.index.values.DocValues;
 
 /**
+ * Abstract API that provides access to one or more per-document storage
+ * features. The concrete implementations provide access to the underlying
+ * storage on a per-document basis corresponding to their actual
+ * {@link PerDocConsumer} counterpart.
+ * <p>
+ * The {@link PerDocValues} API is accessible through flexible indexing / the
+ * {@link Codec} - API providing per field consumers and producers for inverted
+ * data (terms, postings) as well as per-document data.
  * 
- * nocommit javadoc
- * @experimental
+ * @lucene.experimental
  */
 public abstract class PerDocValues implements Closeable {
   /**
@@ -40,5 +47,9 @@ public abstract class PerDocValues implements Closeable {
 
   public static final PerDocValues[] EMPTY_ARRAY = new PerDocValues[0];
 
+  /**
+   * Returns all fields this {@link PerDocValues} contains values for.
+   */
   public abstract Collection<String> fields();
+  
 }

lucene/src/java/org/apache/lucene/index/values/DocValues.java

@@ -27,7 +27,7 @@ import org.apache.lucene.util.AttributeSource;
 import org.apache.lucene.util.BytesRef;
 
 /**
- * TODO
+ * nocommit - javadoc 
  * 
  * @see FieldsEnum#docValues()
  * @see Fields#docValues(String)

lucene/src/test/org/apache/lucene/index/values/TestDocValuesIndexing.java

@@ -69,10 +69,8 @@ public class TestDocValuesIndexing extends LuceneTestCase {
    * 
    * - Add documentation for: 
    *  - DocValues 
-   * - Add @lucene.experimental to all necessary classes 
    * - add test for unoptimized case with deletes
    * - add multithreaded tests / integrate into stress indexing?
-   * - run RAT
    */
 
   @Before