LUCENE-1872: Some formatting changes and addons.

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

src/java/org/apache/lucene/analysis/NumericTokenStream.java

@@ -42,38 +42,39 @@ import org.apache.lucene.analysis.tokenattributes.PositionIncrementAttribute;
  * <p>See {@link NumericField} for capabilities of fields
  * indexed numerically.</p>
  *
- * <p>Here's an example usage, for an int field:
+ * <p>Here's an example usage, for an <code>int</code> field:
  *
  * <pre>
- *   Field field = new Field(name, new NumericTokenStream(precisionStep).setIntValue(value));
- *   field.setOmitNorms(true);
- *   field.setOmitTermFreqAndPositions(true);
- *   document.add(field);
+ *  Field field = new Field(name, new NumericTokenStream(precisionStep).setIntValue(value));
+ *  field.setOmitNorms(true);
+ *  field.setOmitTermFreqAndPositions(true);
+ *  document.add(field);
  * </pre>
  *
  * <p>For optimal performance, re-use the TokenStream and Field instance
  * for more than one document:
  *
  * <pre>
- *   NumericTokenStream stream = new NumericTokenStream(precisionStep);
- *   Field field = new Field(name, stream);
- *   field.setOmitNorms(true);
- *   field.setOmitTermFreqAndPositions(true);
- *   Document document = new Document();
- *   document.add(field);
- *   for(all documents) {
- *     stream.setIntValue(value)
- *     writer.addDocument(document);
- *   }
+ *  NumericTokenStream stream = new NumericTokenStream(precisionStep);
+ *  Field field = new Field(name, stream);
+ *  field.setOmitNorms(true);
+ *  field.setOmitTermFreqAndPositions(true);
+ *  Document document = new Document();
+ *  document.add(field);
+ *
+ *  for(all documents) {
+ *    stream.setIntValue(value)
+ *    writer.addDocument(document);
+ *  }
  * </pre>
  *
  * <p>This stream is not intended to be used in analyzers;
  * it's more for iterating the different precisions during
  * indexing a specific numeric value.</p>
 
- * <p><b>NOTE</b>: as TokenStreams are only consumed once
- * the Document is added to the index, if you index more
- * than one numeric field, use a separate NumericTokenStream
+ * <p><b>NOTE</b>: as token streams are only consumed once
+ * the document is added to the index, if you index more
+ * than one numeric field, use a separate <code>NumericTokenStream</code>
  * instance for each.</p>
  *
  * <p>See {@link NumericRangeQuery} for more details on the

src/java/org/apache/lucene/document/NumericField.java

@@ -32,15 +32,14 @@ import org.apache.lucene.search.FieldCache; // javadocs
  * of numeric values for efficient range filtering and
  * sorting.  Here's an example usage, adding an int value:
  * <pre>
- *   document.add(new NumericField(name).setIntValue(value));
+ *  document.add(new NumericField(name).setIntValue(value));
  * </pre>
  *
  * For optimal performance, re-use the
- * NumericField and {@link Document} instance for more than
+ * <code>NumericField</code> and {@link Document} instance for more than
  * one document:
  *
  * <pre>
- *  <em>// init</em>
  *  NumericField field = new NumericField(name);
  *  Document document = new Document();
  *  document.add(field);
@@ -53,46 +52,50 @@ import org.apache.lucene.search.FieldCache; // javadocs
  *  }
  * </pre>
  *
- * <p>The java native types int, long, float and double are
+ * <p>The java native types <code>int</code>, <code>long</code>,
+ * <code>float</code> and <code>double</code> are
  * directly supported.  However, any value that can be
  * converted into these native types can also be indexed.
  * For example, date/time values represented by a
- * <code>java.util.Date</code> can be translated into a long
- * value using the <code>getTime</code> method.  If you
+ * {@link java.util.Date} can be translated into a long
+ * value using the {@link java.util.Date#getTime} method.  If you
  * don't need millisecond precision, you can quantize the
  * value, either by dividing the result of
- * <code>getTime</code> or using the separate getters (for
- * year, month, etc.) to construct an int or long value.</p>
+ * {@link java.util.Date#getTime} or using the separate getters
+ * (for year, month, etc.) to construct an <code>int</code> or
+ * <code>long</code> value.</p>
  *
  * <p>To perform range querying or filtering against a
- * NumericField, use {@link NumericRangeQuery} or {@link
+ * <code>NumericField</code>, use {@link NumericRangeQuery} or {@link
  * NumericRangeFilter}.  To sort according to a
- * NumericField, use the normal numeric sort types, eg
+ * <code>NumericField</code>, use the normal numeric sort types, eg
  * {@link SortField#INT} (note that {@link SortField#AUTO}
- * will not work with these fields).  NumericField values
+ * will not work with these fields).  <code>NumericField</code> values
  * can also be loaded directly from {@link FieldCache}.</p>
  *
- * <p>By default, a NumericField's value is not stored but
+ * <p>By default, a <code>NumericField</code>'s value is not stored but
  * is indexed for range filtering and sorting.  You can use
  * the {@link #NumericField(String,Field.Store,boolean)}
  * constructor if you need to change these defaults.</p>
  *
- * <p>You may add the same field name as a NumericField to
+ * <p>You may add the same field name as a <code>NumericField</code> to
  * the same document more than once.  Range querying and
- * filtering will be the logical OR of all values, however
- * sort behavior is not defined.  If you need to sort, you
- * should separately index a single-valued NumericField.</p>
+ * filtering will be the logical OR of all values; so a range query
+ * will hit all documents that have at least one value in
+ * the range. However sort behavior is not defined.  If you need to sort,
+ * you should separately index a single-valued <code>NumericField</code>.</p>
  *
- * <p>A NumericField will consume somewhat more disk space
+ * <p>A <code>NumericField</code> will consume somewhat more disk space
  * in the index than an ordindary single-valued field.
  * However, for a typical index that includes substantial
  * textual content per document, this increase will likely
  * be in the noise. </p>
  *
- * <p>Within lucene, each numeric value is indexed as a
+ * <p>Within Lucene, each numeric value is indexed as a
  * <em>trie</em> structure, where each term is logically
- * assigned to larger and larger pre-defined brackets.  The
- * step size between each successive bracket is called the
+ * assigned to larger and larger pre-defined brackets (which
+ * are simply lower-precision representations of the value).
+ * The step size between each successive bracket is called the
  * <code>precisionStep</code>, measured in bits.  Smaller
  * <code>precisionStep</code> values result in larger number
  * of brackets, which consumes more disk space in the index
@@ -105,6 +108,12 @@ import org.apache.lucene.search.FieldCache; // javadocs
  * specify a congruent value when creating {@link
  * NumericRangeQuery} or {@link NumericRangeFilter}.
  *
+ * <p>For more information on the internals of numeric trie
+ * indexing, including the <a
+ * href="../search/NumericRangeQuery.html#precisionStepDesc"><code>precisionStep</code></a>
+ * configuration, see {@link NumericRangeQuery}. The format of
+ * indexed values is described in {@link NumericUtils}.
+ *
  * <p>If you only need to sort by numeric value, and never
  * run range querying/filtering, you can index using a
  * <code>precisionStep</code> of {@link Integer#MAX_VALUE}.
@@ -115,11 +124,6 @@ import org.apache.lucene.search.FieldCache; // javadocs
  * class is a wrapper around this token stream type for
  * easier, more intuitive usage.</p>
  *
- * <p>For more information on the internals of numeric trie
- * indexing, including the <a
- * href="../search/NumericRangeQuery.html#precisionStepDesc"><code>precisionStep</code></a>
- * configuration, see {@link NumericRangeQuery}.
- *
  * <p><b>NOTE:</b> This class is only used during
  * indexing. When retrieving the stored field value from a
  * {@link Document} instance after search, you will get a

src/java/org/apache/lucene/search/NumericRangeFilter.java

@@ -38,14 +38,13 @@ import org.apache.lucene.util.NumericUtils; // for javadocs
  *
  * accepts all documents whose float valued "weight" field
  * ranges from 0.3 to 0.10, inclusive.
+ * See {@link NumericRangeQuery} for details on how Lucene
+ * indexes and searches numeric valued fields.
  *
  * <p><font color="red"><b>NOTE:</b> This API is experimental and
  * might change in incompatible ways in the next
  * release.</font>
  *
- * See {@link NumericRangeQuery} for details on how Lucene
- * indexes and searches numeric valued fields.
- *
  * @since 2.9
  **/
 public final class NumericRangeFilter extends MultiTermQueryWrapperFilter {

src/java/org/apache/lucene/search/NumericRangeQuery.java

@@ -79,8 +79,7 @@ import org.apache.lucene.index.Term;
  * <p><font color="red"><b>NOTE:</b> This API is experimental and
  * might change in incompatible ways in the next release.</font>
  *
- *
- * <br><br><h3>How it works</h3>
+ * <br><h3>How it works</h3>
  *
  * <p>See the publication about <a target="_blank" href="http://www.panfmp.org">panFMP</a>,
  * where this algorithm was described (referred to as <code>TrieRangeQuery</code>):