javadoc cleanups and enhancements

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

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

@@ -62,7 +62,7 @@ import java.util.HashMap;
  * This analyzer is used to facilitate scenarios where different
  * fields require different analysis techniques.  Use {@link #addAnalyzer}
  * to add a non-default analyzer on a field name basis.
- * See {@link TestPerFieldAnalyzerWrapper} for example usage.
+ * See TestPerFieldAnalyzerWrapper.java for example usage.
  */
 public class PerFieldAnalyzerWrapper extends Analyzer {
   private Analyzer defaultAnalyzer;

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

@@ -80,7 +80,7 @@ public final class StopFilter extends TokenFilter {
    * Constructs a filter which removes words from the input
    * TokenStream that are named in the Hashtable.
    *
-   * @deprecated Use {@link #StopFilter(TokenStream, Set)} StopFilter(TokenStream,Map)} instead
+   * @deprecated Use {@link #StopFilter(TokenStream, Set)} instead
    */
   public StopFilter(TokenStream in, Hashtable stopTable) {
     super(in);
@@ -106,7 +106,7 @@ public final class StopFilter extends TokenFilter {
    * This permits this table construction to be cached once when
    * an Analyzer is constructed.
    *
-   * @deprecated Use {@link #makeStopSet(String[] makeStopSet) instead.
+   * @deprecated Use {@link #makeStopSet(String[])} instead.
    */
   public static final Hashtable makeStopTable(String[] stopWords) {
     Hashtable stopTable = new Hashtable(stopWords.length);

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

@@ -59,15 +59,22 @@ import java.util.List;
 import java.util.ArrayList;
 import java.util.Vector;
 import org.apache.lucene.index.IndexReader;       // for javadoc
+import org.apache.lucene.search.Searcher;         // for javadoc
 import org.apache.lucene.search.Hits;             // for javadoc
 
 /** Documents are the unit of indexing and search.
  *
  * A Document is a set of fields.  Each field has a name and a textual value.
- * A field may be stored with the document, in which case it is returned with
+ * A field may be {@link Field#isStored() stored} with the document, in which
- * search hits on the document.  Thus each document should typically contain
+ * case it is returned with search hits on the document.  Thus each document
- * stored fields which uniquely identify it.
+ * should typically contain one or more stored fields which uniquely identify
- * */
+ * it.
+ *
+ * <p>Note that fields which are <i>not</i> {@link Field#isStored() stored} are
+ * <i>not</i> available in documents retrieved from the index, e.g. with {@link
+ * Hits#doc(int)}, {@link Searcher#doc(int)} or {@link
+ * IndexReader#document(int)}.
+ */
 
 public final class Document implements java.io.Serializable {
   List fields = new Vector();
@@ -113,8 +120,9 @@ public final class Document implements java.io.Serializable {
   }
 
   /** Returns a field with the given name if any exist in this document, or
-    null.  If multiple fields exists with this name, this method returns the
+   * null.  If multiple fields exists with this name, this method returns the
-    last field value added. */
+   * first value added.
+   */
   public final Field getField(String name) {
     for (int i = 0; i < fields.size(); i++) {
       Field field = (Field)fields.get(i);
@@ -125,8 +133,9 @@ public final class Document implements java.io.Serializable {
   }
 
   /** Returns the string value of the field with the given name if any exist in
-    this document, or null.  If multiple fields exist with this name, this
+   * this document, or null.  If multiple fields exist with this name, this
-    method returns the last value added. */
+   * method returns the first value added.
+   */
   public final String get(String name) {
     Field field = getField(name);
     if (field != null)
@@ -165,7 +174,6 @@ public final class Document implements java.io.Serializable {
   /**
    * Returns an array of values of the field specified as the method parameter.
    * This method can return <code>null</code>.
-   * UnStored fields' values cannot be returned by this method.
    *
    * @param name the name of the field
    * @return a <code>String[]</code> of field values

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

@@ -163,7 +163,7 @@ public class IndexWriter {
    * @param create <code>true</code> to create the index or overwrite
    *  the existing one; <code>false</code> to append to the existing
    *  index
-   * @param IOException if the directory cannot be read/written to, or
+   * @throws IOException if the directory cannot be read/written to, or
    *  if it does not exist, and <code>create</code> is
    *  <code>false</code>
    */
@@ -183,7 +183,7 @@ public class IndexWriter {
    * @param create <code>true</code> to create the index or overwrite
    *  the existing one; <code>false</code> to append to the existing
    *  index
-   * @param IOException if the directory cannot be read/written to, or
+   * @throws IOException if the directory cannot be read/written to, or
    *  if it does not exist, and <code>create</code> is
    *  <code>false</code>
    */
@@ -198,12 +198,12 @@ public class IndexWriter {
    * is true, then a new, empty index will be created in
    * <code>d</code>, replacing the index already there, if any.
    *
-   * @param path the path to the index directory
+   * @param d the index directory
    * @param a the analyzer to use
    * @param create <code>true</code> to create the index or overwrite
    *  the existing one; <code>false</code> to append to the existing
    *  index
-   * @param IOException if the directory cannot be read/written to, or
+   * @throws IOException if the directory cannot be read/written to, or
    *  if it does not exist, and <code>create</code> is
    *  <code>false</code>
    */

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

@@ -120,7 +120,7 @@ public final class Hits {
     return length;
   }
 
-  /** Returns the nth document in this set.
+  /** Returns the stored fields of the n<sup>th</sup> document in this set.
    <p>Documents are cached, so that repeated requests for the same element may
    return the same Document object. */
   public final Document doc(int n) throws IOException {

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

@@ -86,44 +86,27 @@ public class IndexSearcher extends Searcher {
     reader = r;
   }
 
-  /**
+  // inherit javadoc
-   * Frees resources associated with this Searcher.
-   * Be careful not to call this method while you are still using objects
-   * like {@link Hits}.
-   */
   public void close() throws IOException {
     reader.close();
   }
 
-  /** Expert: Returns the number of documents containing <code>term</code>.
+  // inherit javadoc
-   * Called by search code to compute term weights.
-   * @see IndexReader#docFreq(Term).
-   */
   public int docFreq(Term term) throws IOException {
     return reader.docFreq(term);
   }
 
-  /** For use by {@link HitCollector} implementations. */
+  // inherit javadoc
   public Document doc(int i) throws IOException {
     return reader.document(i);
   }
 
-  /** Expert: Returns one greater than the largest possible document number.
+  // inherit javadoc
-   * Called by search code to compute term weights.
-   * @see IndexReader#maxDoc().
-   */
   public int maxDoc() throws IOException {
     return reader.maxDoc();
   }
 
-  /** Expert: Low-level search implementation.  Finds the top <code>n</code>
+  // inherit javadoc
-   * hits for <code>query</code>, applying <code>filter</code> if non-null.
-   *
-   * <p>Called by {@link Hits}.
-   *
-   * <p>Applications should usually call {@link #search(Query)} or {@link
-   * #search(Query,Filter)} instead.
-   */
   public TopDocs search(Query query, Filter filter, final int nDocs)
        throws IOException {
     Scorer scorer = query.weight(this).scorer(reader);
@@ -150,15 +133,7 @@ public class IndexSearcher extends Searcher {
     return new TopDocs(totalHits[0], scoreDocs);
   }
 
-  /** Expert: Low-level search implementation.  Finds the top <code>n</code>
+  // inherit javadoc
-   * hits for <code>query</code>, applying <code>filter</code> if non-null.
-   * Results are ordered as specified by <code>sort</code>.
-   *
-   * <p>Called by {@link Hits}.
-   *
-   * <p>Applications should usually call {@link #search(Query)} or {@link
-   * #search(Query,Filter)} instead.
-   */
   public TopFieldDocs search(Query query, Filter filter, final int nDocs,
                              Sort sort)
     throws IOException {
@@ -188,20 +163,7 @@ public class IndexSearcher extends Searcher {
   }
 
 
-  /** Lower-level search API.
+  // inherit javadoc
-   *
-   * <p>{@link HitCollector#collect(int,float)} is called for every non-zero
-   * scoring document.
-   *
-   * <p>Applications should only use this if they need <i>all</i> of the
-   * matching documents.  The high-level search API ({@link
-   * Searcher#search(Query)}) is usually more efficient, as it skips
-   * non-high-scoring hits.
-   *
-   * @param query to match documents
-   * @param filter if non-null, a bitset used to eliminate some documents
-   * @param results to receive hits
-   */
   public void search(Query query, Filter filter,
                      final HitCollector results) throws IOException {
     HitCollector collector = results;

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

@@ -85,7 +85,7 @@ public class MultiSearcher extends Searcher {
   	return starts;
   }
 
-  /** Frees resources associated with this <code>Searcher</code>. */
+  // inherit javadoc
   public void close() throws IOException {
     for (int i = 0; i < searchables.length; i++)
       searchables[i].close();
@@ -98,7 +98,7 @@ public class MultiSearcher extends Searcher {
     return docFreq;
   }
 
-  /** For use by {@link HitCollector} implementations. */
+  // inherit javadoc
   public Document doc(int n) throws IOException {
     int i = subSearcher(n);			  // find searcher index
     return searchables[i].doc(n - starts[i]);	  // dispatch to searcher
@@ -196,20 +196,7 @@ public class MultiSearcher extends Searcher {
   }
 
 
-  /** Lower-level search API.
+  // inherit javadoc
-   *
-   * <p>{@link HitCollector#collect(int,float)} is called for every non-zero
-   * scoring document.
-   *
-   * <p>Applications should only use this if they need <i>all</i> of the
-   * matching documents.  The high-level search API ({@link
-   * Searcher#search(Query)}) is usually more efficient, as it skips
-   * non-high-scoring hits.
-   *
-   * @param query to match documents
-   * @param filter if non-null, a bitset used to eliminate some documents
-   * @param results to receive hits
-   */
   public void search(Query query, Filter filter, final HitCollector results)
     throws IOException {
     for (int i = 0; i < searchables.length; i++) {

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

@@ -83,7 +83,10 @@ public interface Searchable extends java.rmi.Remote {
   void search(Query query, Filter filter, HitCollector results)
     throws IOException;
 
-  /** Frees resources associated with this Searcher. */
+  /** Frees resources associated with this Searcher.
+   * Be careful not to call this method while you are still using objects
+   * like {@link Hits}.
+   */
   void close() throws IOException;
 
   /** Expert: Returns the number of documents containing <code>term</code>.

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

@@ -58,7 +58,7 @@ import java.io.Serializable;
  * not be tokenized.  The values are sorted according to their
  * {@link Comparable natural order}.  Note that using this type
  * of term value has higher memory requirements than the other
- * two types - see {@link FieldSortedHitQueue FieldSortedHitQueue}.
+ * two types.
  *
  * <p><h3>Object Reuse</h3>
  *