improve (Indexable)FieldType docs

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

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

@@ -17,6 +17,7 @@ package org.apache.lucene.document;
  * limitations under the License.
  */
 
+import org.apache.lucene.analysis.Analyzer; // javadocs
 import org.apache.lucene.index.DocValues;
 import org.apache.lucene.index.FieldInfo.IndexOptions;
 import org.apache.lucene.index.IndexableFieldType;
@@ -47,6 +48,9 @@ public class FieldType implements IndexableFieldType {
   private boolean frozen;
   private int numericPrecisionStep = NumericUtils.PRECISION_STEP_DEFAULT;
 
+  /**
+   * Create a new mutable FieldType with all of the properties from <code>ref</code>
+   */
   public FieldType(FieldType ref) {
     this.indexed = ref.indexed();
     this.stored = ref.stored();
@@ -62,6 +66,9 @@ public class FieldType implements IndexableFieldType {
     // Do not copy frozen!
   }
   
+  /**
+   * Create a new FieldType with default properties.
+   */
   public FieldType() {
   }
 
@@ -80,110 +87,227 @@ public class FieldType implements IndexableFieldType {
     this.frozen = true;
   }
   
+  /**
+   * {@inheritDoc}
+   * <p>
+   * The default is <code>false</code>.
+   * @see #setIndexed(boolean)
+   */
   public boolean indexed() {
     return this.indexed;
   }
   
+  /**
+   * Set to <code>true</code> to index (invert) this field.
+   * @see #indexed()
+   */
   public void setIndexed(boolean value) {
     checkIfFrozen();
     this.indexed = value;
   }
 
+  /**
+   * {@inheritDoc}
+   * <p>
+   * The default is <code>false</code>.
+   * @see #setStored(boolean)
+   */
   public boolean stored() {
     return this.stored;
   }
   
+  /**
+   * Set to <code>true</code> to store this field.
+   * @see #stored()
+   */
   public void setStored(boolean value) {
     checkIfFrozen();
     this.stored = value;
   }
 
+  /**
+   * {@inheritDoc}
+   * <p>
+   * The default is <code>true</code>.
+   * @see #setTokenized(boolean)
+   */
   public boolean tokenized() {
     return this.tokenized;
   }
   
+  /**
+   * Set to <code>true</code> to tokenize this field's contents via the 
+   * configured {@link Analyzer}.
+   * @see #tokenized()
+   */
   public void setTokenized(boolean value) {
     checkIfFrozen();
     this.tokenized = value;
   }
 
+  /**
+   * {@inheritDoc}
+   * <p>
+   * The default is <code>false</code>. 
+   * @see #setStoreTermVectors(boolean)
+   */
   public boolean storeTermVectors() {
     return this.storeTermVectors;
   }
   
+  /**
+   * Set to <code>true</code> if this field's indexed form should be also stored 
+   * into term vectors.
+   * @see #storeTermVectors()
+   */
   public void setStoreTermVectors(boolean value) {
     checkIfFrozen();
     this.storeTermVectors = value;
   }
 
+  /**
+   * {@inheritDoc}
+   * <p>
+   * The default is <code>false</code>.
+   * @see #setStoreTermVectorOffsets(boolean)
+   */
   public boolean storeTermVectorOffsets() {
     return this.storeTermVectorOffsets;
   }
   
+  /**
+   * Set to <code>true</code> to also store token character offsets into the term
+   * vector for this field.
+   * @see #storeTermVectorOffsets()
+   */
   public void setStoreTermVectorOffsets(boolean value) {
     checkIfFrozen();
     this.storeTermVectorOffsets = value;
   }
 
+  /**
+   * {@inheritDoc}
+   * <p>
+   * The default is <code>false</code>.
+   * @see #setStoreTermVectorPositions(boolean)
+   */
   public boolean storeTermVectorPositions() {
     return this.storeTermVectorPositions;
   }
   
+  /**
+   * Set to <code>true</code> to also store token positions into the term
+   * vector for this field.
+   * @see #storeTermVectorPositions()
+   */
   public void setStoreTermVectorPositions(boolean value) {
     checkIfFrozen();
     this.storeTermVectorPositions = value;
   }
   
+  /**
+   * {@inheritDoc}
+   * <p>
+   * The default is <code>false</code>.
+   * @see #setStoreTermVectorPayloads(boolean) 
+   */
   public boolean storeTermVectorPayloads() {
     return this.storeTermVectorPayloads;
   }
   
+  /**
+   * Set to <code>true</code> to also store token payloads into the term
+   * vector for this field.
+   * @see #storeTermVectorPayloads()
+   */
   public void setStoreTermVectorPayloads(boolean value) {
     checkIfFrozen();
     this.storeTermVectorPayloads = value;
   }
   
+  /**
+   * {@inheritDoc}
+   * <p>
+   * The default is <code>false</code>.
+   * @see #setOmitNorms(boolean)
+   */
   public boolean omitNorms() {
     return this.omitNorms;
   }
   
+  /**
+   * Set to <code>true</code> to omit normalization values for the field.
+   * @see #omitNorms()
+   */
   public void setOmitNorms(boolean value) {
     checkIfFrozen();
     this.omitNorms = value;
   }
 
+  /**
+   * {@inheritDoc}
+   * <p>
+   * The default is {@link IndexOptions#DOCS_AND_FREQS_AND_POSITIONS}.
+   * @see #setIndexOptions(FieldInfo.IndexOptions)
+   */
   public IndexOptions indexOptions() {
     return this.indexOptions;
   }
   
+  /**
+   * Sets the indexing options for the field:
+   * @see #indexOptions()
+   */
   public void setIndexOptions(IndexOptions value) {
     checkIfFrozen();
     this.indexOptions = value;
   }
 
+  /**
+   * Set's the field's DocValues.Type
+   * @see #docValueType()
+   */
   public void setDocValueType(DocValues.Type type) {
     checkIfFrozen();
     docValueType = type;
   }
   
+  /**
+   * {@inheritDoc}
+   * <p>
+   * The default is <code>null</code> (no docValues) 
+   * @see #setDocValueType(DocValues.Type)
+   */
   @Override
   public DocValues.Type docValueType() {
     return docValueType;
   }
 
+  /**
+   * Specifies the field's numeric type.
+   * @see #numericType()
+   */
   public void setNumericType(NumericType type) {
     checkIfFrozen();
     numericType = type;
   }
 
-  /** NumericDataType; if
+  /** 
-   *  non-null then the field's value will be indexed
+   * NumericType: if non-null then the field's value will be indexed
-   *  numerically so that {@link NumericRangeQuery} can be
+   * numerically so that {@link NumericRangeQuery} can be used at 
-   *  used at search time. */
+   * search time. 
+   * <p>
+   * The default is <code>null</code> (no numeric type) 
+   * @see #setNumericType(NumericType)
+   */
   public NumericType numericType() {
     return numericType;
   }
 
+  /**
+   * Sets the numeric precision step for the field.
+   * @see #numericPrecisionStep()
+   */
   public void setNumericPrecisionStep(int precisionStep) {
     checkIfFrozen();
     if (precisionStep < 1) {
@@ -192,7 +316,14 @@ public class FieldType implements IndexableFieldType {
     this.numericPrecisionStep = precisionStep;
   }
 
-  /** Precision step for numeric field. */
+  /** 
+   * Precision step for numeric field. 
+   * <p>
+   * This has no effect if {@link #numericType()} returns null.
+   * <p>
+   * The default is {@link NumericUtils#PRECISION_STEP_DEFAULT}
+   * @see #setNumericPrecisionStep(int)
+   */
   public int numericPrecisionStep() {
     return numericPrecisionStep;
   }

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

@@ -55,14 +55,29 @@ public final class FieldInfo {
     // NOTE: order is important here; FieldInfo uses this
     // order to merge two conflicting IndexOptions (always
     // "downgrades" by picking the lowest).
-    /** only documents are indexed: term frequencies and positions are omitted */
+    /** 
+     * Only documents are indexed: term frequencies and positions are omitted.
+     * Phrase and other positional queries on the field will throw an exception, and scoring
+     * will behave as if any term in the document appears only once.
+     */
     // TODO: maybe rename to just DOCS?
     DOCS_ONLY,
-    /** only documents and term frequencies are indexed: positions are omitted */  
+    /** 
+     * Only documents and term frequencies are indexed: positions are omitted. 
+     * This enables normal scoring, except Phrase and other positional queries
+     * will throw an exception.
+     */  
     DOCS_AND_FREQS,
-    /** documents, frequencies and positions */
+    /** 
+     * Indexes documents, frequencies and positions.
+     * This is a typical default for full-text search: full scoring is enabled
+     * and positional queries are supported.
+     */
     DOCS_AND_FREQS_AND_POSITIONS,
-    /** documents, frequencies, positions and offsets */
+    /** 
+     * Indexes documents, frequencies, positions and offsets.
+     * Character offsets are encoded alongside the positions. 
+     */
     DOCS_AND_FREQS_AND_POSITIONS_AND_OFFSETS,
   };
 

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

@@ -17,6 +17,7 @@ package org.apache.lucene.index;
  * limitations under the License.
  */
 
+import org.apache.lucene.analysis.Analyzer; // javadocs
 import org.apache.lucene.index.FieldInfo.IndexOptions;
 
 /** 
@@ -31,29 +32,68 @@ public interface IndexableFieldType {
   /** True if the field's value should be stored */
   public boolean stored();
 
-  /** True if this field's value should be analyzed */
+  /** 
+   * True if this field's value should be analyzed by the
+   * {@link Analyzer}.
+   * <p>
+   * This has no effect if {@link #indexed()} returns false.
+   */
   public boolean tokenized();
 
-  /** True if term vectors should be indexed */
+  /** 
+   * True if this field's indexed form should be also stored 
+   * into term vectors.
+   * <p>
+   * This builds a miniature inverted-index for this field which
+   * can be accessed in a document-oriented way from 
+   * {@link IndexReader#getTermVector(int,String)}.
+   * <p>
+   * This option is illegal if {@link #indexed()} returns false.
+   */
   public boolean storeTermVectors();
 
-  /** True if term vector offsets should be indexed */
+  /** 
+   * True if this field's token character offsets should also
+   * be stored into term vectors.
+   * <p>
+   * This option is illegal if term vectors are not enabled for the field
+   * ({@link #storeTermVectors()} is false)
+   */
   public boolean storeTermVectorOffsets();
 
-  /** True if term vector positions should be indexed */
+  /** 
+   * True if this field's token positions should also be stored
+   * into the term vectors.
+   * <p>
+   * This option is illegal if term vectors are not enabled for the field
+   * ({@link #storeTermVectors()} is false). 
+   */
   public boolean storeTermVectorPositions();
   
-  /** True if term vector payloads should be indexed */
+  /** 
+   * True if this field's token payloads should also be stored
+   * into the term vectors.
+   * <p>
+   * This option is illegal if term vector positions are not enabled 
+   * for the field ({@link #storeTermVectors()} is false).
+   */
   public boolean storeTermVectorPayloads();
 
-  /** True if norms should not be indexed */
+  /**
+   * True if normalization values should be omitted for the field.
+   * <p>
+   * This saves memory, but at the expense of scoring quality (length normalization
+   * will be disabled), and if you omit norms, you cannot use index-time boosts. 
+   */
   public boolean omitNorms();
 
   /** {@link IndexOptions}, describing what should be
    * recorded into the inverted index */
   public IndexOptions indexOptions();
 
-  /** DocValues type; if non-null then the field's value
+  /** 
-   *  will be indexed into docValues */
+   * DocValues {@link DocValues.Type}: if non-null then the field's value
+   * will be indexed into docValues.
+   */
   public DocValues.Type docValueType();
 }