diff --git a/src/java/org/apache/lucene/analysis/PerFieldAnalyzerWrapper.java b/src/java/org/apache/lucene/analysis/PerFieldAnalyzerWrapper.java index 1cb5e68d7c0..16ad782de08 100644 --- a/src/java/org/apache/lucene/analysis/PerFieldAnalyzerWrapper.java +++ b/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; diff --git a/src/java/org/apache/lucene/analysis/StopFilter.java b/src/java/org/apache/lucene/analysis/StopFilter.java index e33345d849f..c5313899d39 100644 --- a/src/java/org/apache/lucene/analysis/StopFilter.java +++ b/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); diff --git a/src/java/org/apache/lucene/document/Document.java b/src/java/org/apache/lucene/document/Document.java index 3bc474919b7..bc9c35a2504 100644 --- a/src/java/org/apache/lucene/document/Document.java +++ b/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 - * search hits on the document. Thus each document should typically contain - * stored fields which uniquely identify it. - * */ + * A field may be {@link Field#isStored() stored} with the document, in which + * case it is returned with search hits on the document. Thus each document + * should typically contain one or more stored fields which uniquely identify + * it. + * + *

Note that fields which are not {@link Field#isStored() stored} are + * not 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 - last field value added. */ + * null. If multiple fields exists with this name, this method returns the + * 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 - method returns the last value added. */ + * this document, or null. If multiple fields exist with this name, this + * 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 null. - * UnStored fields' values cannot be returned by this method. * * @param name the name of the field * @return a String[] of field values diff --git a/src/java/org/apache/lucene/index/IndexWriter.java b/src/java/org/apache/lucene/index/IndexWriter.java index b77a05e87ce..9ab765e581b 100644 --- a/src/java/org/apache/lucene/index/IndexWriter.java +++ b/src/java/org/apache/lucene/index/IndexWriter.java @@ -163,7 +163,7 @@ public class IndexWriter { * @param create true to create the index or overwrite * the existing one; false 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 create is * false */ @@ -183,7 +183,7 @@ public class IndexWriter { * @param create true to create the index or overwrite * the existing one; false 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 create is * false */ @@ -198,12 +198,12 @@ public class IndexWriter { * is true, then a new, empty index will be created in * d, 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 true to create the index or overwrite * the existing one; false 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 create is * false */ diff --git a/src/java/org/apache/lucene/search/Hits.java b/src/java/org/apache/lucene/search/Hits.java index 08323b1e015..d6c0e5e3690 100644 --- a/src/java/org/apache/lucene/search/Hits.java +++ b/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 nth document in this set.

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 { diff --git a/src/java/org/apache/lucene/search/IndexSearcher.java b/src/java/org/apache/lucene/search/IndexSearcher.java index d9de677e76d..d4df87e9845 100644 --- a/src/java/org/apache/lucene/search/IndexSearcher.java +++ b/src/java/org/apache/lucene/search/IndexSearcher.java @@ -86,44 +86,27 @@ public class IndexSearcher extends Searcher { reader = r; } - /** - * Frees resources associated with this Searcher. - * Be careful not to call this method while you are still using objects - * like {@link Hits}. - */ + // inherit javadoc public void close() throws IOException { reader.close(); } - /** Expert: Returns the number of documents containing term. - * Called by search code to compute term weights. - * @see IndexReader#docFreq(Term). - */ + // inherit javadoc 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. - * Called by search code to compute term weights. - * @see IndexReader#maxDoc(). - */ + // inherit javadoc public int maxDoc() throws IOException { return reader.maxDoc(); } - /** Expert: Low-level search implementation. Finds the top n - * hits for query, applying filter if non-null. - * - *

Called by {@link Hits}. - * - *

Applications should usually call {@link #search(Query)} or {@link - * #search(Query,Filter)} instead. - */ + // inherit javadoc 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 n - * hits for query, applying filter if non-null. - * Results are ordered as specified by sort. - * - *

Called by {@link Hits}. - * - *

Applications should usually call {@link #search(Query)} or {@link - * #search(Query,Filter)} instead. - */ + // inherit javadoc 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. - * - *

{@link HitCollector#collect(int,float)} is called for every non-zero - * scoring document. - * - *

Applications should only use this if they need all 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 - */ + // inherit javadoc public void search(Query query, Filter filter, final HitCollector results) throws IOException { HitCollector collector = results; diff --git a/src/java/org/apache/lucene/search/MultiSearcher.java b/src/java/org/apache/lucene/search/MultiSearcher.java index f76e79686e9..0297f2b4c3c 100644 --- a/src/java/org/apache/lucene/search/MultiSearcher.java +++ b/src/java/org/apache/lucene/search/MultiSearcher.java @@ -85,7 +85,7 @@ public class MultiSearcher extends Searcher { return starts; } - /** Frees resources associated with this Searcher. */ + // 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. - * - *

{@link HitCollector#collect(int,float)} is called for every non-zero - * scoring document. - * - *

Applications should only use this if they need all 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 - */ + // inherit javadoc public void search(Query query, Filter filter, final HitCollector results) throws IOException { for (int i = 0; i < searchables.length; i++) { diff --git a/src/java/org/apache/lucene/search/Searchable.java b/src/java/org/apache/lucene/search/Searchable.java index 10b90558ccd..0558c7d1a7a 100644 --- a/src/java/org/apache/lucene/search/Searchable.java +++ b/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 term. diff --git a/src/java/org/apache/lucene/search/Sort.java b/src/java/org/apache/lucene/search/Sort.java index c134a553482..f4a62ad8bed 100644 --- a/src/java/org/apache/lucene/search/Sort.java +++ b/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. * *

Object Reuse

*