From 4f76db565010ddba6544415d9fc1c7f45e77ddd6 Mon Sep 17 00:00:00 2001 From: Robert Muir Date: Mon, 27 Aug 2012 20:36:18 +0000 Subject: [PATCH] improve these javadocs git-svn-id: https://svn.apache.org/repos/asf/lucene/dev/trunk@1377836 13f79535-47bb-0310-9956-ffa450edef68 --- .../org/apache/lucene/analysis/Analyzer.java | 19 ++++++++++++++++++ .../lucene/analysis/CachingTokenFilter.java | 12 +++++++++++ .../java/org/apache/lucene/codecs/Codec.java | 12 +++++++++++ .../apache/lucene/codecs/PostingsFormat.java | 20 +++++++++++++++++++ 4 files changed, 63 insertions(+) diff --git a/lucene/core/src/java/org/apache/lucene/analysis/Analyzer.java b/lucene/core/src/java/org/apache/lucene/analysis/Analyzer.java index 13679bdc47d..0ff186f7696 100644 --- a/lucene/core/src/java/org/apache/lucene/analysis/Analyzer.java +++ b/lucene/core/src/java/org/apache/lucene/analysis/Analyzer.java @@ -71,10 +71,22 @@ public abstract class Analyzer { private final ReuseStrategy reuseStrategy; + /** + * Create a new Analyzer, reusing the same set of components per-thread + * across calls to {@link #tokenStream(String, Reader)}. + */ public Analyzer() { this(new GlobalReuseStrategy()); } + /** + * Expert: create a new Analyzer with a custom {@link ReuseStrategy}. + *

+ * NOTE: if you just want to reuse on a per-field basis, its easier to + * use a subclass of {@link AnalyzerWrapper} such as + * + * PerFieldAnalyerWrapper instead. + */ public Analyzer(ReuseStrategy reuseStrategy) { this.reuseStrategy = reuseStrategy; } @@ -171,7 +183,14 @@ public abstract class Analyzer { * {@link Analyzer#tokenStream(String, Reader)}. */ public static class TokenStreamComponents { + /** + * Original source of the tokens. + */ protected final Tokenizer source; + /** + * Sink tokenstream, such as the outer tokenfilter decorating + * the chain. This can be the source if there are no filters. + */ protected final TokenStream sink; /** diff --git a/lucene/core/src/java/org/apache/lucene/analysis/CachingTokenFilter.java b/lucene/core/src/java/org/apache/lucene/analysis/CachingTokenFilter.java index a6c1e822a77..e71452af165 100644 --- a/lucene/core/src/java/org/apache/lucene/analysis/CachingTokenFilter.java +++ b/lucene/core/src/java/org/apache/lucene/analysis/CachingTokenFilter.java @@ -38,6 +38,11 @@ public final class CachingTokenFilter extends TokenFilter { private Iterator iterator = null; private AttributeSource.State finalState; + /** + * Create a new CachingTokenFilter around input, + * caching its token attributes, which can be replayed again + * after a call to {@link #reset()}. + */ public CachingTokenFilter(TokenStream input) { super(input); } @@ -67,6 +72,13 @@ public final class CachingTokenFilter extends TokenFilter { } } + /** + * Rewinds the iterator to the beginning of the cached list. + *

+ * Note that this does not call reset() on the wrapped tokenstream ever, even + * the first time. You should reset() the inner tokenstream before wrapping + * it with CachingTokenFilter. + */ @Override public void reset() { if(cache != null) { diff --git a/lucene/core/src/java/org/apache/lucene/codecs/Codec.java b/lucene/core/src/java/org/apache/lucene/codecs/Codec.java index c7f46e452ce..ddff816a62c 100644 --- a/lucene/core/src/java/org/apache/lucene/codecs/Codec.java +++ b/lucene/core/src/java/org/apache/lucene/codecs/Codec.java @@ -41,6 +41,14 @@ public abstract class Codec implements NamedSPILoader.NamedSPI { private final String name; + /** + * Creates a new codec. + *

+ * The provided name will be written into the index segment: in order to + * for the segment to be read this class should be registered with Java's + * SPI mechanism (registered in META-INF/ of your jar file, etc). + * @param name must be all ascii alphanumeric, and less than 128 characters in length. + */ public Codec(String name) { NamedSPILoader.checkServiceName(name); this.name = name; @@ -118,6 +126,10 @@ public abstract class Codec implements NamedSPILoader.NamedSPI { defaultCodec = codec; } + /** + * returns the codec's name. Subclasses can override to provide + * more detail (such as parameters). + */ @Override public String toString() { return name; diff --git a/lucene/core/src/java/org/apache/lucene/codecs/PostingsFormat.java b/lucene/core/src/java/org/apache/lucene/codecs/PostingsFormat.java index 0c48c1a767b..27f237b167b 100644 --- a/lucene/core/src/java/org/apache/lucene/codecs/PostingsFormat.java +++ b/lucene/core/src/java/org/apache/lucene/codecs/PostingsFormat.java @@ -18,14 +18,24 @@ package org.apache.lucene.codecs; */ import java.io.IOException; +import java.util.ServiceLoader; import java.util.Set; +import org.apache.lucene.codecs.perfield.PerFieldPostingsFormat; // javadocs import org.apache.lucene.index.SegmentWriteState; import org.apache.lucene.index.SegmentReadState; import org.apache.lucene.util.NamedSPILoader; /** * Encodes/decodes terms, postings, and proximity data. + *

+ * Note, when extending this class, the name ({@link #getName}) may + * written into the index in certain configurations. In order for the segment + * to be read, the name must resolve to your implementation via {@link #forName(String)}. + * This method uses Java's + * {@link ServiceLoader Service Provider Interface} to resolve codec names. + *

+ * @see ServiceLoader * @lucene.experimental */ public abstract class PostingsFormat implements NamedSPILoader.NamedSPI { @@ -38,11 +48,21 @@ public abstract class PostingsFormat implements NamedSPILoader.NamedSPI { */ private final String name; + /** + * Creates a new postings format. + *

+ * The provided name will be written into the index segment in some configurations + * (such as when using {@link PerFieldPostingsFormat}): in such configurations, + * for the segment to be read this class should be registered with Java's + * SPI mechanism (registered in META-INF/ of your jar file, etc). + * @param name must be all ascii alphanumeric, and less than 128 characters in length. + */ protected PostingsFormat(String name) { NamedSPILoader.checkServiceName(name); this.name = name; } + /** Returns this posting format's name */ @Override public final String getName() { return name;