Index: src/java/org/apache/lucene/analysis/StopFilter.java
===================================================================
--- src/java/org/apache/lucene/analysis/StopFilter.java	(revision 885594)
+++ src/java/org/apache/lucene/analysis/StopFilter.java	(working copy)
@@ -35,8 +35,8 @@
  * compatibility when creating StopFilter:
  * <ul>
  *   <li> As of 3.1, StopFilter correctly handles Unicode 4.0
- *         supplementary characters in stopwords and position
- *         increments are preserved
+ *         supplementary characters in stopwords.
+ *   <li> As of 2.9, position increments are preserved
  * </ul>
  */
 public final class StopFilter extends TokenFilter {
@@ -81,8 +81,8 @@
    * to specify the case sensitivity of that set.
    * 
    * @param matchVersion
-   *          Lucene version to enable correct Unicode 4.0 behavior in the stop
-   *          set if Version > 3.0. See <a href="#version">above</a> for details.
+   *          Lucene version to match. 
+   *          See <a href="#version">above</a> for details.
    * @param input
    *          Input TokenStream
    * @param stopWords
@@ -96,10 +96,31 @@
    this(matchVersion, matchVersion.onOrAfter(Version.LUCENE_29), input, stopWords, ignoreCase);
   }
   
-  /*
-   * convenience ctor to enable deprecated ctors to set posInc explicitly
+  /**
+   * Construct a token stream filtering the given input. If
+   * <code>stopWords</code> is an instance of {@link CharArraySet} (true if
+   * <code>makeStopSet()</code> was used to construct the set) it will be
+   * directly used and <code>ignoreCase</code> will be ignored since
+   * <code>CharArraySet</code> directly controls case sensitivity.
+   * <p/>
+   * If <code>stopWords</code> is not an instance of {@link CharArraySet}, a new
+   * CharArraySet will be constructed and <code>ignoreCase</code> will be used
+   * to specify the case sensitivity of that set.
+   * 
+   * @param matchVersion
+   *          Lucene version to enable correct Unicode 4.0 behavior in the stop
+   *          set if Version > 3.0. See <a href="#version">above</a> for details.
+   * @param enablePositionIncrements true if the position increments should be
+   *          adjusted for removed stopwords.
+   * @param input
+   *          Input TokenStream
+   * @param stopWords
+   *          A Set of Strings or char[] or any other toString()-able set
+   *          representing the stopwords
+   * @param ignoreCase
+   *          if true, all words are lower cased first
    */
-  private StopFilter(Version matchVersion, boolean enablePositionIncrements, TokenStream input, Set<?> stopWords, boolean ignoreCase){
+  public StopFilter(Version matchVersion, boolean enablePositionIncrements, TokenStream input, Set<?> stopWords, boolean ignoreCase){
     super(input);
     this.stopWords = CharArraySet.unmodifiableSet(new CharArraySet(matchVersion, stopWords, ignoreCase));
     this.enablePositionIncrements = enablePositionIncrements;
@@ -126,8 +147,8 @@
    * named in the Set.
    * 
    * @param matchVersion
-   *          Lucene version to enable correct Unicode 4.0 behavior in the stop
-   *          set if Version > 3.0.  See <a href="#version">above</a> for details.
+   *          Lucene version to match. 
+   *          See <a href="#version">above</a> for details.
    * @param in
    *          Input stream
    * @param stopWords
@@ -297,6 +318,9 @@
    * <p> <b>NOTE</b>: be sure to also
    * set {@link QueryParser#setEnablePositionIncrements} if
    * you use QueryParser to create queries.
+   * @deprecated Use 
+   *     {@link #StopFilter(Version, boolean, TokenStream, Set, boolean)}
+   *     to specify this explicitly in the constructor instead.
    */
   public void setEnablePositionIncrements(boolean enable) {
     this.enablePositionIncrements = enable;