lucene-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From rm...@apache.org
Subject svn commit: r1377837 - in /lucene/dev/branches/branch_4x: ./ lucene/ lucene/core/ lucene/core/src/java/org/apache/lucene/analysis/ lucene/core/src/java/org/apache/lucene/codecs/
Date Mon, 27 Aug 2012 20:36:43 GMT
Author: rmuir
Date: Mon Aug 27 20:36:43 2012
New Revision: 1377837

URL: http://svn.apache.org/viewvc?rev=1377837&view=rev
Log:
improve these javadocs

Modified:
    lucene/dev/branches/branch_4x/   (props changed)
    lucene/dev/branches/branch_4x/lucene/   (props changed)
    lucene/dev/branches/branch_4x/lucene/core/   (props changed)
    lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/analysis/Analyzer.java
    lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/analysis/CachingTokenFilter.java
    lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/codecs/Codec.java
    lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/codecs/PostingsFormat.java

Modified: lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/analysis/Analyzer.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/analysis/Analyzer.java?rev=1377837&r1=1377836&r2=1377837&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/analysis/Analyzer.java
(original)
+++ lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/analysis/Analyzer.java
Mon Aug 27 20:36:43 2012
@@ -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;
 
     /**

Modified: lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/analysis/CachingTokenFilter.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/analysis/CachingTokenFilter.java?rev=1377837&r1=1377836&r2=1377837&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/analysis/CachingTokenFilter.java
(original)
+++ lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/analysis/CachingTokenFilter.java
Mon Aug 27 20:36:43 2012
@@ -38,6 +38,11 @@ public final class CachingTokenFilter ex
   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 ex
     }
   }
 
+  /**
+   * 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) {

Modified: lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/codecs/Codec.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/codecs/Codec.java?rev=1377837&r1=1377836&r2=1377837&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/codecs/Codec.java
(original)
+++ lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/codecs/Codec.java
Mon Aug 27 20:36:43 2012
@@ -41,6 +41,14 @@ public abstract class Codec implements N
 
   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 N
     defaultCodec = codec;
   }
 
+  /**
+   * returns the codec's name. Subclasses can override to provide
+   * more detail (such as parameters).
+   */
   @Override
   public String toString() {
     return name;

Modified: lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/codecs/PostingsFormat.java
URL: http://svn.apache.org/viewvc/lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/codecs/PostingsFormat.java?rev=1377837&r1=1377836&r2=1377837&view=diff
==============================================================================
--- lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/codecs/PostingsFormat.java
(original)
+++ lucene/dev/branches/branch_4x/lucene/core/src/java/org/apache/lucene/codecs/PostingsFormat.java
Mon Aug 27 20:36:43 2012
@@ -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 imp
    */
   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;



Mime
View raw message