svn commit: r1525825 - /lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/TokenStream.java

[us...@apache.org]

Author: uschindler
Date: Tue Sep 24 09:53:21 2013
New Revision: 1525825

URL: http://svn.apache.org/r1525825
Log:
LUCENE-5235: Update Javadocs to make it explicit that super.reset(), super.close() and super.end() must be called.

Modified:
    lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/TokenStream.java

Modified: lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/TokenStream.java
URL: http://svn.apache.org/viewvc/lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/TokenStream.java?rev=1525825&r1=1525824&r2=1525825&view=diff
==============================================================================
--- lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/TokenStream.java (original)
+++ lucene/dev/trunk/lucene/core/src/java/org/apache/lucene/analysis/TokenStream.java Tue Sep 24 09:53:21 2013
@@ -164,6 +164,8 @@ public abstract class TokenStream extend
    * Additionally any skipped positions (such as those removed by a stopfilter)
    * can be applied to the position increment, or any adjustment of other
    * attributes where the end-of-stream value may be important.
+   * <p>
+   * If you override this method, always call {@code super.end()}.
    * 
    * @throws IOException If an I/O error occurs
    */
@@ -177,13 +179,22 @@ public abstract class TokenStream extend
   /**
    * This method is called by a consumer before it begins consumption using
    * {@link #incrementToken()}.
-   * <p/>
+   * <p>
    * Resets this stream to a clean state. Stateful implementations must implement
    * this method so that they can be reused, just as if they had been created fresh.
+   * <p>
+   * If you override this method, always call {@code super.reset()}, otherwise
+   * some internal state will not be correctly reset (e.g., {@link Tokenizer} will
+   * throw {@link IllegalStateException} on further usage).
    */
   public void reset() throws IOException {}
   
-  /** Releases resources associated with this stream. */
+  /** Releases resources associated with this stream.
+   * <p>
+   * If you override this method, always call {@code super.close()}, otherwise
+   * some internal state will not be correctly reset (e.g., {@link Tokenizer} will
+   * throw {@link IllegalStateException} on reuse).
+   */
   @Override
   public void close() throws IOException {}