improve these javadocs

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

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}.
+   * <p>
+   * NOTE: if you just want to reuse on a per-field basis, its easier to
+   * use a subclass of {@link AnalyzerWrapper} such as 
+   * <a href="{@docRoot}/../analyzers-common/org/apache/lucene/analysis/miscellaneous/PerFieldAnalyzerWrapper.html">
+   * PerFieldAnalyerWrapper</a> 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;
 
     /**

lucene/core/src/java/org/apache/lucene/analysis/CachingTokenFilter.java

@@ -38,6 +38,11 @@ public final class CachingTokenFilter extends TokenFilter {
   private Iterator<AttributeSource.State> iterator = null; 
   private AttributeSource.State finalState;
   
+  /**
+   * Create a new CachingTokenFilter around <code>input</code>,
+   * 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.
+   * <p>
+   * 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) {

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.
+   * <p>
+   * 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;

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.
+ * <p>
+ * 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.
+ * <p>
+ * @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.
+   * <p>
+   * 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;