javadocs

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

lucene/build.xml

@@ -251,6 +251,7 @@
 
       <!-- too much to fix for now, but enforce full javadocs for key packages -->
       <check-missing-javadocs dir="build/docs/core/org/apache/lucene/analysis" level="method"/>
+      <check-missing-javadocs dir="build/docs/core/org/apache/lucene/document" level="method"/>
     </sequential>
   </target>
   

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

@@ -38,12 +38,21 @@ import org.apache.lucene.index.DocValues;
 
 public class ByteDocValuesField extends Field {
 
+  /**
+   * Type for 8-bit byte DocValues.
+   */
   public static final FieldType TYPE = new FieldType();
   static {
     TYPE.setDocValueType(DocValues.Type.FIXED_INTS_8);
     TYPE.freeze();
   }
 
+  /** 
+   * Creates a new DocValues field with the specified 8-bit byte value 
+   * @param name field name
+   * @param value 8-bit byte value
+   * @throws IllegalArgumentException if the field name is null.
+   */
   public ByteDocValuesField(String name, byte value) {
     super(name, TYPE);
     fieldsData = Byte.valueOf(value);

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

@@ -92,10 +92,14 @@ public class CompressionTools {
     return compress(result.bytes, 0, result.length, compressionLevel);
   }
 
+  /** Decompress the byte array previously returned by
+   *  compress (referenced by the provided BytesRef) */
   public static byte[] decompress(BytesRef bytes) throws DataFormatException {
     return decompress(bytes.bytes, bytes.offset, bytes.length);
   }
 
+  /** Decompress the byte array previously returned by
+   *  compress */
   public static byte[] decompress(byte[] value) throws DataFormatException {
     return decompress(value, 0, value.length);
   }
@@ -130,6 +134,8 @@ public class CompressionTools {
     return decompressString(value, 0, value.length);
   }
 
+  /** Decompress the byte array previously returned by
+   *  compressString back into a String */
   public static String decompressString(byte[] value, int offset, int length) throws DataFormatException {
     final byte[] bytes = decompress(value, offset, length);
     CharsRef result = new CharsRef(bytes.length);
@@ -137,6 +143,8 @@ public class CompressionTools {
     return new String(result.chars, 0, result.length);
   }
 
+  /** Decompress the byte array (referenced by the provided BytesRef) 
+   *  previously returned by compressString back into a String */
   public static String decompressString(BytesRef bytes) throws DataFormatException {
     return decompressString(bytes.bytes, bytes.offset, bytes.length);
   }

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

@@ -185,7 +185,20 @@ public class DateTools {
   /** Specifies the time granularity. */
   public static enum Resolution {
     
-    YEAR(4), MONTH(6), DAY(8), HOUR(10), MINUTE(12), SECOND(14), MILLISECOND(17);
+    /** Limit a date's resolution to year granularity. */
+    YEAR(4), 
+    /** Limit a date's resolution to month granularity. */
+    MONTH(6), 
+    /** Limit a date's resolution to day granularity. */
+    DAY(8), 
+    /** Limit a date's resolution to hour granularity. */
+    HOUR(10), 
+    /** Limit a date's resolution to minute granularity. */
+    MINUTE(12), 
+    /** Limit a date's resolution to second granularity. */
+    SECOND(14), 
+    /** Limit a date's resolution to millisecond granularity. */
+    MILLISECOND(17);
 
     final int formatLen;
     final SimpleDateFormat format;//should be cloned before use, since it's not threadsafe

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

@@ -44,23 +44,49 @@ import org.apache.lucene.util.BytesRef;
 public class DerefBytesDocValuesField extends Field {
 
   // TODO: ideally indexer figures out var vs fixed on its own!?
+  /**
+   * Type for indirect bytes DocValues: all with the same length
+   */
   public static final FieldType TYPE_FIXED_LEN = new FieldType();
   static {
     TYPE_FIXED_LEN.setDocValueType(DocValues.Type.BYTES_FIXED_DEREF);
     TYPE_FIXED_LEN.freeze();
   }
 
+  /**
+   * Type for indirect bytes DocValues: can have variable lengths
+   */
   public static final FieldType TYPE_VAR_LEN = new FieldType();
   static {
     TYPE_VAR_LEN.setDocValueType(DocValues.Type.BYTES_VAR_DEREF);
     TYPE_VAR_LEN.freeze();
   }
 
+  /**
+   * Create a new variable-length indirect DocValues field.
+   * <p>
+   * This calls 
+   * {@link DerefBytesDocValuesField#DerefBytesDocValuesField(String, BytesRef, boolean)
+   *  DerefBytesDocValuesField(name, bytes, false}, meaning by default
+   * it allows for values of different lengths. If your values are all 
+   * the same length, use that constructor instead.
+   * @param name field name
+   * @param bytes binary content
+   * @throws IllegalArgumentException if the field name is null
+   */
   public DerefBytesDocValuesField(String name, BytesRef bytes) {
     super(name, TYPE_VAR_LEN);
     fieldsData = bytes;
   }
 
+  /**
+   * Create a new fixed or variable length indirect DocValues field.
+   * <p>
+   * @param name field name
+   * @param bytes binary content
+   * @param isFixedLength true if all values have the same length.
+   * @throws IllegalArgumentException if the field name is null
+   */
   public DerefBytesDocValuesField(String name, BytesRef bytes, boolean isFixedLength) {
     super(name, isFixedLength ? TYPE_FIXED_LEN : TYPE_VAR_LEN);
     fieldsData = bytes;

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

@@ -96,6 +96,13 @@ public class DocumentStoredFieldVisitor extends StoredFieldVisitor {
     return fieldsToAdd == null || fieldsToAdd.contains(fieldInfo.name) ? Status.YES : Status.NO;
   }
 
+  /**
+   * Retrieve the visited document.
+   * @return Document populated with stored fields. Note that only
+   *         the stored information in the field instances is valid,
+   *         data such as boosts, indexing options, term vector options,
+   *         etc is not set.
+   */
   public Document getDocument() {
     return doc;
   }

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

@@ -38,12 +38,21 @@ import org.apache.lucene.index.DocValues;
 
 public class DoubleDocValuesField extends Field {
 
+  /**
+   * Type for 64-bit double DocValues.
+   */
   public static final FieldType TYPE = new FieldType();
   static {
     TYPE.setDocValueType(DocValues.Type.FLOAT_64);
     TYPE.freeze();
   }
 
+  /** 
+   * Creates a new DocValues field with the specified 64-bit double value 
+   * @param name field name
+   * @param value 64-bit double value
+   * @throws IllegalArgumentException if the field name is null
+   */
   public DoubleDocValuesField(String name, double value) {
     super(name, TYPE);
     fieldsData = Double.valueOf(value);

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

@@ -114,6 +114,10 @@ import org.apache.lucene.util.NumericUtils;
 
 public final class DoubleField extends Field {
   
+  /** 
+   * Type for a DoubleField that is not stored:
+   * normalization factors, frequencies, and positions are omitted.
+   */
   public static final FieldType TYPE_NOT_STORED = new FieldType();
   static {
     TYPE_NOT_STORED.setIndexed(true);
@@ -124,6 +128,10 @@ public final class DoubleField extends Field {
     TYPE_NOT_STORED.freeze();
   }
 
+  /** 
+   * Type for a stored DoubleField:
+   * normalization factors, frequencies, and positions are omitted.
+   */
   public static final FieldType TYPE_STORED = new FieldType();
   static {
     TYPE_STORED.setIndexed(true);
@@ -137,14 +145,26 @@ public final class DoubleField extends Field {
 
   /** Creates a stored or un-stored DoubleField with the provided value
    *  and default <code>precisionStep</code> {@link
-   *  NumericUtils#PRECISION_STEP_DEFAULT} (4). */
+   *  NumericUtils#PRECISION_STEP_DEFAULT} (4). 
+   *  @param name field name
+   *  @param value 64-bit double value
+   *  @param stored Store.YES if the content should also be stored
+   *  @throws IllegalArgumentException if the field name is null. 
+   */
   public DoubleField(String name, double value, Store stored) {
     super(name, stored == Store.YES ? TYPE_STORED : TYPE_NOT_STORED);
     fieldsData = Double.valueOf(value);
   }
   
   /** Expert: allows you to customize the {@link
-   *  FieldType}. */
+   *  FieldType}. 
+   *  @param name field name
+   *  @param value 64-bit double value
+   *  @param type customized field type: must have {@link FieldType#numericType()}
+   *         of {@link FieldType.NumericType#DOUBLE}.
+   *  @throws IllegalArgumentException if the field name or type is null, or
+   *          if the field type does not have a DOUBLE numericType()
+   */
   public DoubleField(String name, double value, FieldType type) {
     super(name, type);
     if (type.numericType() != FieldType.NumericType.DOUBLE) {

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

@@ -90,6 +90,10 @@ public class Field implements IndexableField {
   /**
    * Expert: creates a field with no initial value.
    * Intended only for custom Field subclasses.
+   * @param name field name
+   * @param type field type
+   * @throws IllegalArgumentException if either the name or type
+   *         is null.
    */
   protected Field(String name, FieldType type) {
     if (name == null) {
@@ -104,6 +108,13 @@ public class Field implements IndexableField {
 
   /**
    * Create field with Reader value.
+   * @param name field name
+   * @param reader reader value
+   * @param type field type
+   * @throws IllegalArgumentException if either the name or type
+   *         is null, or if the field's type is stored(), or
+   *         if tokenized() is false.
+   * @throws NullPointerException if the reader is null
    */
   public Field(String name, Reader reader, FieldType type) {
     if (name == null) {
@@ -129,6 +140,13 @@ public class Field implements IndexableField {
 
   /**
    * Create field with TokenStream value.
+   * @param name field name
+   * @param tokenStream TokenStream value
+   * @param type field type
+   * @throws IllegalArgumentException if either the name or type
+   *         is null, or if the field's type is stored(), or
+   *         if tokenized() is false, or if indexed() is false.
+   * @throws NullPointerException if the tokenStream is null
    */
   public Field(String name, TokenStream tokenStream, FieldType type) {
     if (name == null) {
@@ -152,6 +170,15 @@ public class Field implements IndexableField {
   
   /**
    * Create field with binary value.
+   * 
+   * <p>NOTE: the provided byte[] is not copied so be sure
+   * not to change it until you're done with this field.
+   * @param name field name
+   * @param value byte array pointing to binary content (not copied)
+   * @param type field type
+   * @throws IllegalArgumentException if the field name is null,
+   *         or the field's type is indexed()
+   * @throws NullPointerException if the type is null
    */
   public Field(String name, byte[] value, FieldType type) {
     this(name, value, 0, value.length, type);
@@ -159,6 +186,17 @@ public class Field implements IndexableField {
 
   /**
    * Create field with binary value.
+   * 
+   * <p>NOTE: the provided byte[] is not copied so be sure
+   * not to change it until you're done with this field.
+   * @param name field name
+   * @param value byte array pointing to binary content (not copied)
+   * @param offset starting position of the byte array
+   * @param length valid length of the byte array
+   * @param type field type
+   * @throws IllegalArgumentException if the field name is null,
+   *         or the field's type is indexed()
+   * @throws NullPointerException if the type is null
    */
   public Field(String name, byte[] value, int offset, int length, FieldType type) {
     this(name, new BytesRef(value, offset, length), type);
@@ -169,6 +207,12 @@ public class Field implements IndexableField {
    *
    * <p>NOTE: the provided BytesRef is not copied so be sure
    * not to change it until you're done with this field.
+   * @param name field name
+   * @param bytes BytesRef pointing to binary content (not copied)
+   * @param type field type
+   * @throws IllegalArgumentException if the field name is null,
+   *         or the field's type is indexed()
+   * @throws NullPointerException if the type is null
    */
   public Field(String name, BytesRef bytes, FieldType type) {
     if (name == null) {
@@ -186,6 +230,13 @@ public class Field implements IndexableField {
 
   /**
    * Create field with String value.
+   * @param name field name
+   * @param value string value
+   * @param type field type
+   * @throws IllegalArgumentException if either the name or value
+   *         is null, or if the field's type is neither indexed() nor stored(), 
+   *         or if indexed() is false but storeTermVectors() is true.
+   * @throws NullPointerException if the type is null
    */
   public Field(String name, String value, FieldType type) {
     if (name == null) {
@@ -390,6 +441,8 @@ public class Field implements IndexableField {
 
   /** 
    * Sets the boost factor on this field.
+   * @throws IllegalArgumentException if this field is not indexed, 
+   *         or if it omits norms. 
    * @see #boost()
    */
   public void setBoost(float boost) {

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

@@ -32,7 +32,16 @@ public class FieldType implements IndexableFieldType {
   /** Data type of the numeric value
    * @since 3.2
    */
-  public static enum NumericType {INT, LONG, FLOAT, DOUBLE}
+  public static enum NumericType {
+    /** 32-bit integer numeric type */
+    INT, 
+    /** 64-bit long numeric type */
+    LONG, 
+    /** 32-bit float numeric type */
+    FLOAT, 
+    /** 64-bit double numeric type */
+    DOUBLE
+  }
 
   private boolean indexed;
   private boolean stored;
@@ -99,6 +108,9 @@ public class FieldType implements IndexableFieldType {
   
   /**
    * Set to <code>true</code> to index (invert) this field.
+   * @param value true if this field should be indexed.
+   * @throws IllegalStateException if this FieldType is frozen against
+   *         future modifications.
    * @see #indexed()
    */
   public void setIndexed(boolean value) {
@@ -118,6 +130,9 @@ public class FieldType implements IndexableFieldType {
   
   /**
    * Set to <code>true</code> to store this field.
+   * @param value true if this field should be stored.
+   * @throws IllegalStateException if this FieldType is frozen against
+   *         future modifications.
    * @see #stored()
    */
   public void setStored(boolean value) {
@@ -138,6 +153,9 @@ public class FieldType implements IndexableFieldType {
   /**
    * Set to <code>true</code> to tokenize this field's contents via the 
    * configured {@link Analyzer}.
+   * @param value true if this field should be tokenized.
+   * @throws IllegalStateException if this FieldType is frozen against
+   *         future modifications.
    * @see #tokenized()
    */
   public void setTokenized(boolean value) {
@@ -158,6 +176,9 @@ public class FieldType implements IndexableFieldType {
   /**
    * Set to <code>true</code> if this field's indexed form should be also stored 
    * into term vectors.
+   * @param value true if this field should store term vectors.
+   * @throws IllegalStateException if this FieldType is frozen against
+   *         future modifications.
    * @see #storeTermVectors()
    */
   public void setStoreTermVectors(boolean value) {
@@ -178,6 +199,9 @@ public class FieldType implements IndexableFieldType {
   /**
    * Set to <code>true</code> to also store token character offsets into the term
    * vector for this field.
+   * @param value true if this field should store term vector offsets.
+   * @throws IllegalStateException if this FieldType is frozen against
+   *         future modifications.
    * @see #storeTermVectorOffsets()
    */
   public void setStoreTermVectorOffsets(boolean value) {
@@ -198,6 +222,9 @@ public class FieldType implements IndexableFieldType {
   /**
    * Set to <code>true</code> to also store token positions into the term
    * vector for this field.
+   * @param value true if this field should store term vector positions.
+   * @throws IllegalStateException if this FieldType is frozen against
+   *         future modifications.
    * @see #storeTermVectorPositions()
    */
   public void setStoreTermVectorPositions(boolean value) {
@@ -218,6 +245,9 @@ public class FieldType implements IndexableFieldType {
   /**
    * Set to <code>true</code> to also store token payloads into the term
    * vector for this field.
+   * @param value true if this field should store term vector payloads.
+   * @throws IllegalStateException if this FieldType is frozen against
+   *         future modifications.
    * @see #storeTermVectorPayloads()
    */
   public void setStoreTermVectorPayloads(boolean value) {
@@ -237,6 +267,9 @@ public class FieldType implements IndexableFieldType {
   
   /**
    * Set to <code>true</code> to omit normalization values for the field.
+   * @param value true if this field should omit norms.
+   * @throws IllegalStateException if this FieldType is frozen against
+   *         future modifications.
    * @see #omitNorms()
    */
   public void setOmitNorms(boolean value) {
@@ -256,6 +289,9 @@ public class FieldType implements IndexableFieldType {
   
   /**
    * Sets the indexing options for the field:
+   * @param value indexing options
+   * @throws IllegalStateException if this FieldType is frozen against
+   *         future modifications.
    * @see #indexOptions()
    */
   public void setIndexOptions(IndexOptions value) {
@@ -265,6 +301,9 @@ public class FieldType implements IndexableFieldType {
 
   /**
    * Set's the field's DocValues.Type
+   * @param type DocValues type, or null if no DocValues should be stored.
+   * @throws IllegalStateException if this FieldType is frozen against
+   *         future modifications.
    * @see #docValueType()
    */
   public void setDocValueType(DocValues.Type type) {
@@ -285,6 +324,9 @@ public class FieldType implements IndexableFieldType {
 
   /**
    * Specifies the field's numeric type.
+   * @param type numeric type, or null if the field has no numeric type.
+   * @throws IllegalStateException if this FieldType is frozen against
+   *         future modifications.
    * @see #numericType()
    */
   public void setNumericType(NumericType type) {
@@ -306,6 +348,10 @@ public class FieldType implements IndexableFieldType {
 
   /**
    * Sets the numeric precision step for the field.
+   * @param precisionStep numeric precision step for the field
+   * @throws IllegalArgumentException if precisionStep is less than 1. 
+   * @throws IllegalStateException if this FieldType is frozen against
+   *         future modifications.
    * @see #numericPrecisionStep()
    */
   public void setNumericPrecisionStep(int precisionStep) {

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

@@ -37,12 +37,21 @@ import org.apache.lucene.index.DocValues;
 
 public class FloatDocValuesField extends Field {
 
+  /**
+   * Type for 32-bit float DocValues.
+   */
   public static final FieldType TYPE = new FieldType();
   static {
     TYPE.setDocValueType(DocValues.Type.FLOAT_32);
     TYPE.freeze();
   }
 
+  /** 
+   * Creates a new DocValues field with the specified 32-bit float value 
+   * @param name field name
+   * @param value 32-bit float value
+   * @throws IllegalArgumentException if the field name is null
+   */
   public FloatDocValuesField(String name, float value) {
     super(name, TYPE);
     fieldsData = Float.valueOf(value);

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

@@ -114,6 +114,10 @@ import org.apache.lucene.util.NumericUtils;
 
 public final class FloatField extends Field {
   
+  /** 
+   * Type for a FloatField that is not stored:
+   * normalization factors, frequencies, and positions are omitted.
+   */
   public static final FieldType TYPE_NOT_STORED = new FieldType();
   static {
     TYPE_NOT_STORED.setIndexed(true);
@@ -124,6 +128,10 @@ public final class FloatField extends Field {
     TYPE_NOT_STORED.freeze();
   }
 
+  /** 
+   * Type for a stored FloatField:
+   * normalization factors, frequencies, and positions are omitted.
+   */
   public static final FieldType TYPE_STORED = new FieldType();
   static {
     TYPE_STORED.setIndexed(true);
@@ -137,14 +145,26 @@ public final class FloatField extends Field {
 
   /** Creates a stored or un-stored FloatField with the provided value
    *  and default <code>precisionStep</code> {@link
-   *  NumericUtils#PRECISION_STEP_DEFAULT} (4). */
+   *  NumericUtils#PRECISION_STEP_DEFAULT} (4). 
+   *  @param name field name
+   *  @param value 32-bit double value
+   *  @param stored Store.YES if the content should also be stored
+   *  @throws IllegalArgumentException if the field name is null.
+   */
   public FloatField(String name, float value, Store stored) {
     super(name, stored == Store.YES ? TYPE_STORED : TYPE_NOT_STORED);
     fieldsData = Float.valueOf(value);
   }
   
   /** Expert: allows you to customize the {@link
-   *  FieldType}. */
+   *  FieldType}. 
+   *  @param name field name
+   *  @param value 32-bit float value
+   *  @param type customized field type: must have {@link FieldType#numericType()}
+   *         of {@link FieldType.NumericType#FLOAT}.
+   *  @throws IllegalArgumentException if the field name or type is null, or
+   *          if the field type does not have a FLOAT numericType()
+   */
   public FloatField(String name, float value, FieldType type) {
     super(name, type);
     if (type.numericType() != FieldType.NumericType.FLOAT) {

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

@@ -37,12 +37,21 @@ import org.apache.lucene.index.DocValues;
 
 public class IntDocValuesField extends Field {
 
+  /**
+   * Type for 32-bit integer DocValues.
+   */
   public static final FieldType TYPE = new FieldType();
   static {
     TYPE.setDocValueType(DocValues.Type.FIXED_INTS_32);
     TYPE.freeze();
   }
 
+  /** 
+   * Creates a new DocValues field with the specified 32-bit integer value 
+   * @param name field name
+   * @param value 32-bit integer value
+   * @throws IllegalArgumentException if the field name is null
+   */
   public IntDocValuesField(String name, int value) {
     super(name, TYPE);
     fieldsData = Integer.valueOf(value);

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

@@ -114,6 +114,10 @@ import org.apache.lucene.util.NumericUtils;
 
 public final class IntField extends Field {
   
+  /** 
+   * Type for an IntField that is not stored:
+   * normalization factors, frequencies, and positions are omitted.
+   */
   public static final FieldType TYPE_NOT_STORED = new FieldType();
   static {
     TYPE_NOT_STORED.setIndexed(true);
@@ -124,6 +128,10 @@ public final class IntField extends Field {
     TYPE_NOT_STORED.freeze();
   }
 
+  /** 
+   * Type for a stored IntField:
+   * normalization factors, frequencies, and positions are omitted.
+   */
   public static final FieldType TYPE_STORED = new FieldType();
   static {
     TYPE_STORED.setIndexed(true);
@@ -137,14 +145,26 @@ public final class IntField extends Field {
 
   /** Creates a stored or un-stored IntField with the provided value
    *  and default <code>precisionStep</code> {@link
-   *  NumericUtils#PRECISION_STEP_DEFAULT} (4). */
+   *  NumericUtils#PRECISION_STEP_DEFAULT} (4). 
+   *  @param name field name
+   *  @param value 32-bit integer value
+   *  @param stored Store.YES if the content should also be stored
+   *  @throws IllegalArgumentException if the field name is null.
+   */
   public IntField(String name, int value, Store stored) {
     super(name, stored == Store.YES ? TYPE_STORED : TYPE_NOT_STORED);
     fieldsData = Integer.valueOf(value);
   }
   
   /** Expert: allows you to customize the {@link
-   *  FieldType}. */
+   *  FieldType}. 
+   *  @param name field name
+   *  @param value 32-bit integer value
+   *  @param type customized field type: must have {@link FieldType#numericType()}
+   *         of {@link FieldType.NumericType#INT}.
+   *  @throws IllegalArgumentException if the field name or type is null, or
+   *          if the field type does not have a INT numericType()
+   */
   public IntField(String name, int value, FieldType type) {
     super(name, type);
     if (type.numericType() != FieldType.NumericType.INT) {

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

@@ -37,12 +37,21 @@ import org.apache.lucene.index.DocValues;
 
 public class LongDocValuesField extends Field {
 
+  /**
+   * Type for 64-bit long DocValues.
+   */
   public static final FieldType TYPE = new FieldType();
   static {
     TYPE.setDocValueType(DocValues.Type.FIXED_INTS_64);
     TYPE.freeze();
   }
 
+  /** 
+   * Creates a new DocValues field with the specified 64-bit long value 
+   * @param name field name
+   * @param value 64-bit long value
+   * @throws IllegalArgumentException if the field name is null
+   */
   public LongDocValuesField(String name, long value) {
     super(name, TYPE);
     fieldsData = Long.valueOf(value);

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

@@ -124,6 +124,10 @@ import org.apache.lucene.util.NumericUtils;
 
 public final class LongField extends Field {
   
+  /** 
+   * Type for a LongField that is not stored:
+   * normalization factors, frequencies, and positions are omitted.
+   */
   public static final FieldType TYPE_NOT_STORED = new FieldType();
   static {
     TYPE_NOT_STORED.setIndexed(true);
@@ -134,6 +138,10 @@ public final class LongField extends Field {
     TYPE_NOT_STORED.freeze();
   }
 
+  /** 
+   * Type for a stored LongField:
+   * normalization factors, frequencies, and positions are omitted.
+   */
   public static final FieldType TYPE_STORED = new FieldType();
   static {
     TYPE_STORED.setIndexed(true);
@@ -147,14 +155,26 @@ public final class LongField extends Field {
 
   /** Creates a stored or un-stored LongField with the provided value
    *  and default <code>precisionStep</code> {@link
-   *  NumericUtils#PRECISION_STEP_DEFAULT} (4). */
+   *  NumericUtils#PRECISION_STEP_DEFAULT} (4). 
+   *  @param name field name
+   *  @param value 64-bit long value
+   *  @param stored Store.YES if the content should also be stored
+   *  @throws IllegalArgumentException if the field name is null.
+   */
   public LongField(String name, long value, Store stored) {
     super(name, stored == Store.YES ? TYPE_STORED : TYPE_NOT_STORED);
     fieldsData = Long.valueOf(value);
   }
   
   /** Expert: allows you to customize the {@link
-   *  FieldType}. */
+   *  FieldType}. 
+   *  @param name field name
+   *  @param value 64-bit long value
+   *  @param type customized field type: must have {@link FieldType#numericType()}
+   *         of {@link FieldType.NumericType#LONG}.
+   *  @throws IllegalArgumentException if the field name or type is null, or
+   *          if the field type does not have a LONG numericType()
+   */
   public LongField(String name, long value, FieldType type) {
     super(name, type);
     if (type.numericType() != FieldType.NumericType.LONG) {

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

@@ -41,12 +41,21 @@ import org.apache.lucene.index.AtomicReader;      // javadocs
 
 public class PackedLongDocValuesField extends Field {
 
+  /**
+   * Type for packed long DocValues.
+   */
   public static final FieldType TYPE = new FieldType();
   static {
     TYPE.setDocValueType(DocValues.Type.VAR_INTS);
     TYPE.freeze();
   }
 
+  /** 
+   * Creates a new DocValues field with the specified long value 
+   * @param name field name
+   * @param value 64-bit long value
+   * @throws IllegalArgumentException if the field name is null
+   */
   public PackedLongDocValuesField(String name, long value) {
     super(name, TYPE);
     fieldsData = Long.valueOf(value);

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

@@ -38,12 +38,21 @@ import org.apache.lucene.index.DocValues;
 
 public class ShortDocValuesField extends Field {
 
+  /**
+   * Type for 16-bit short DocValues.
+   */
   public static final FieldType TYPE = new FieldType();
   static {
     TYPE.setDocValueType(DocValues.Type.FIXED_INTS_16);
     TYPE.freeze();
   }
 
+  /** 
+   * Creates a new DocValues field with the specified 16-bit short value 
+   * @param name field name
+   * @param value 16-bit short value
+   * @throws IllegalArgumentException if the field name is null
+   */
   public ShortDocValuesField(String name, short value) {
     super(name, TYPE);
     fieldsData = Short.valueOf(value);

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

@@ -40,22 +40,47 @@ import org.apache.lucene.util.BytesRef;
 public class SortedBytesDocValuesField extends Field {
 
   // TODO: ideally indexer figures out var vs fixed on its own!?
+  /**
+   * Type for sorted bytes DocValues: all with the same length
+   */
   public static final FieldType TYPE_FIXED_LEN = new FieldType();
   static {
     TYPE_FIXED_LEN.setDocValueType(DocValues.Type.BYTES_FIXED_SORTED);
     TYPE_FIXED_LEN.freeze();
   }
 
+  /**
+   * Type for sorted bytes DocValues: can have variable lengths
+   */
   public static final FieldType TYPE_VAR_LEN = new FieldType();
   static {
     TYPE_VAR_LEN.setDocValueType(DocValues.Type.BYTES_VAR_SORTED);
     TYPE_VAR_LEN.freeze();
   }
 
+  /**
+   * Create a new variable-length sorted DocValues field.
+   * <p>
+   * This calls 
+   * {@link SortedBytesDocValuesField#SortedBytesDocValuesField(String, BytesRef, boolean)
+   *  SortedBytesDocValuesField(name, bytes, false}, meaning by default
+   * it allows for values of different lengths. If your values are all 
+   * the same length, use that constructor instead.
+   * @param name field name
+   * @param bytes binary content
+   * @throws IllegalArgumentException if the field name is null
+   */
   public SortedBytesDocValuesField(String name, BytesRef bytes) {
     this(name, bytes, false);
   }
 
+  /**
+   * Create a new fixed or variable length sorted DocValues field.
+   * @param name field name
+   * @param bytes binary content
+   * @param isFixedLength true if all values have the same length.
+   * @throws IllegalArgumentException if the field name is null
+   */
   public SortedBytesDocValuesField(String name, BytesRef bytes, boolean isFixedLength) {
     super(name, isFixedLength ? TYPE_FIXED_LEN : TYPE_VAR_LEN);
     fieldsData = bytes;

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

@@ -26,6 +26,9 @@ import org.apache.lucene.util.BytesRef;
  *  return the field and its value. */
 public final class StoredField extends Field {
 
+  /**
+   * Type for a stored-only field.
+   */
   public final static FieldType TYPE;
   static {
     TYPE = new FieldType();
@@ -33,38 +36,94 @@ public final class StoredField extends Field {
     TYPE.freeze();
   }
 
+  /**
+   * Create a stored-only field with the given binary value.
+   * <p>NOTE: the provided byte[] is not copied so be sure
+   * not to change it until you're done with this field.
+   * @param name field name
+   * @param value byte array pointing to binary content (not copied)
+   * @throws IllegalArgumentException if the field name is null.
+   */
   public StoredField(String name, byte[] value) {
     super(name, value, TYPE);
   }
   
+  /**
+   * Create a stored-only field with the given binary value.
+   * <p>NOTE: the provided byte[] is not copied so be sure
+   * not to change it until you're done with this field.
+   * @param name field name
+   * @param value byte array pointing to binary content (not copied)
+   * @param offset starting position of the byte array
+   * @param length valid length of the byte array
+   * @throws IllegalArgumentException if the field name is null.
+   */
   public StoredField(String name, byte[] value, int offset, int length) {
     super(name, value, offset, length, TYPE);
   }
 
+  /**
+   * Create a stored-only field with the given binary value.
+   * <p>NOTE: the provided BytesRef is not copied so be sure
+   * not to change it until you're done with this field.
+   * @param name field name
+   * @param value BytesRef pointing to binary content (not copied)
+   * @throws IllegalArgumentException if the field name is null.
+   */
   public StoredField(String name, BytesRef value) {
     super(name, value, TYPE);
   }
 
+  /**
+   * Create a stored-only field with the given string value.
+   * @param name field name
+   * @param value string value
+   * @throws IllegalArgumentException if the field name or value is null.
+   */
   public StoredField(String name, String value) {
     super(name, value, TYPE);
   }
 
   // TODO: not great but maybe not a big problem?
+  /**
+   * Create a stored-only field with the given integer value.
+   * @param name field name
+   * @param value integer value
+   * @throws IllegalArgumentException if the field name is null.
+   */
   public StoredField(String name, int value) {
     super(name, TYPE);
     fieldsData = value;
   }
 
+  /**
+   * Create a stored-only field with the given float value.
+   * @param name field name
+   * @param value float value
+   * @throws IllegalArgumentException if the field name is null.
+   */
   public StoredField(String name, float value) {
     super(name, TYPE);
     fieldsData = value;
   }
 
+  /**
+   * Create a stored-only field with the given long value.
+   * @param name field name
+   * @param value long value
+   * @throws IllegalArgumentException if the field name is null.
+   */
   public StoredField(String name, long value) {
     super(name, TYPE);
     fieldsData = value;
   }
 
+  /**
+   * Create a stored-only field with the given double value.
+   * @param name field name
+   * @param value double value
+   * @throws IllegalArgumentException if the field name is null.
+   */
   public StoredField(String name, double value) {
     super(name, TYPE);
     fieldsData = value;

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

@@ -43,23 +43,49 @@ import org.apache.lucene.util.BytesRef;
 public class StraightBytesDocValuesField extends Field {
 
   // TODO: ideally indexer figures out var vs fixed on its own!?
+  /**
+   * Type for direct bytes DocValues: all with the same length
+   */
   public static final FieldType TYPE_FIXED_LEN = new FieldType();
   static {
     TYPE_FIXED_LEN.setDocValueType(DocValues.Type.BYTES_FIXED_STRAIGHT);
     TYPE_FIXED_LEN.freeze();
   }
 
+  /**
+   * Type for direct bytes DocValues: can have variable lengths
+   */
   public static final FieldType TYPE_VAR_LEN = new FieldType();
   static {
     TYPE_VAR_LEN.setDocValueType(DocValues.Type.BYTES_VAR_STRAIGHT);
     TYPE_VAR_LEN.freeze();
   }
 
+  /**
+   * Create a new variable-length direct DocValues field.
+   * <p>
+   * This calls 
+   * {@link StraightBytesDocValuesField#StraightBytesDocValuesField(String, BytesRef, boolean)
+   *  StraightBytesDocValuesField(name, bytes, false}, meaning by default
+   * it allows for values of different lengths. If your values are all 
+   * the same length, use that constructor instead.
+   * @param name field name
+   * @param bytes binary content
+   * @throws IllegalArgumentException if the field name is null
+   */
   public StraightBytesDocValuesField(String name, BytesRef bytes) {
     super(name, TYPE_VAR_LEN);
     fieldsData = bytes;
   }
 
+  /**
+   * Create a new fixed or variable length direct DocValues field.
+   * <p>
+   * @param name field name
+   * @param bytes binary content
+   * @param isFixedLength true if all values have the same length.
+   * @throws IllegalArgumentException if the field name is null
+   */
   public StraightBytesDocValuesField(String name, BytesRef bytes, boolean isFixedLength) {
     super(name, isFixedLength ? TYPE_FIXED_LEN : TYPE_VAR_LEN);
     fieldsData = bytes;

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

@@ -50,7 +50,12 @@ public final class StringField extends Field {
     TYPE_STORED.freeze();
   }
 
-  /** Creates a new StringField. */
+  /** Creates a new StringField. 
+   *  @param name field name
+   *  @param value String value
+   *  @param stored Store.YES if the content should also be stored
+   *  @throws IllegalArgumentException if the field name or value is null.
+   */
   public StringField(String name, String value, Store stored) {
     super(name, value, stored == Store.YES ? TYPE_STORED : TYPE_NOT_STORED);
   }

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

@@ -46,17 +46,32 @@ public final class TextField extends Field {
 
   // TODO: add sugar for term vectors...?
 
-  /** Creates a new un-stored TextField with Reader value. */
+  /** Creates a new un-stored TextField with Reader value. 
+   * @param name field name
+   * @param reader reader value
+   * @throws IllegalArgumentException if the field name is null
+   * @throws NullPointerException if the reader is null
+   */
   public TextField(String name, Reader reader) {
     super(name, reader, TYPE_NOT_STORED);
   }
 
-  /** Creates a new TextField with String value. */
+  /** Creates a new TextField with String value. 
+   * @param name field name
+   * @param value string value
+   * @param store Store.YES if the content should also be stored
+   * @throws IllegalArgumentException if the field name or value is null.
+   */
   public TextField(String name, String value, Store store) {
     super(name, value, store == Store.YES ? TYPE_STORED : TYPE_NOT_STORED);
   }
   
-  /** Creates a new un-stored TextField with TokenStream value. */
+  /** Creates a new un-stored TextField with TokenStream value. 
+   * @param name field name
+   * @param stream TokenStream value
+   * @throws IllegalArgumentException if the field name is null.
+   * @throws NullPointerException if the tokenStream is null
+   */
   public TextField(String name, TokenStream stream) {
     super(name, stream, TYPE_NOT_STORED);
   }