Fix-up of JavaDocs for filters (and a couple of style fixes too).

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@272615 13f79535-47bb-0310-9956-ffa450edef68

src/main/org/apache/tools/ant/filters/BaseFilterReader.java

@@ -207,13 +207,14 @@ public abstract class BaseFilterReader
     protected final String readLine() throws IOException {
         int ch = in.read();
         
-        if (ch==-1)
+        if (ch == -1) {
             return null;
+        }
             
         StringBuffer line = new StringBuffer();
                 
         while (ch != -1) {
-            line.append ((char)ch);
+            line.append ((char) ch);
             if (ch == '\n') {
                 break;
             }

src/main/org/apache/tools/ant/filters/BaseParamFilterReader.java

@@ -59,7 +59,7 @@ import org.apache.tools.ant.types.Parameter;
 import org.apache.tools.ant.types.Parameterizable;
 
 /**
- * Parameterized Base class for core filter readers.
+ * Parameterized base class for core filter readers.
  *
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
@@ -70,32 +70,41 @@ public abstract class BaseParamFilterReader
     private Parameter[] parameters;
 
     /**
-     * This constructor is a dummy constructor and is
-     * not meant to be used by any class other than Ant's
-     * introspection mechanism. This will close the filter
-     * that is created making it useless for further operations.
+     * Constructor for "dummy" instances.
+     * 
+     * @see BaseFilterReader#BaseFilterReader()
      */
     public BaseParamFilterReader() {
         super();
     }
 
     /**
-     * Create a new filtered reader.
+     * Creates a new filtered reader.
      *
-     * @param in  a Reader object providing the underlying stream.
+     * @param in A Reader object providing the underlying stream.
+     *           Must not be <code>null</code>.
      */
     public BaseParamFilterReader(final Reader in) {
         super(in);
     }
 
     /**
-     * Set Parameters
+     * Sets the parameters used by this filter, and sets
+     * the filter to an uninitialized status.
+     * 
+     * @param parameters The parameters to be used by this filter.
+     *                   Should not be <code>null</code>.
      */
     public final void setParameters(final Parameter[] parameters) {
         this.parameters = parameters;
         setInitialized(false);
     }
 
+    /**
+     * Returns the parameters to be used by this filter.
+     * 
+     * @return the parameters to be used by this filter
+     */
     protected final Parameter[] getParameters() {
         return parameters;
     }

src/main/org/apache/tools/ant/filters/ChainableReader.java

@@ -56,10 +56,19 @@ package org.apache.tools.ant.filters;
 import java.io.Reader;
 
 /**
- * Chains readers.
+ * Interface indicating that a reader may be chained to another one.
  *
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
 public interface ChainableReader {
+    /**
+     * Returns a reader with the same configuration as this one,
+     * but filtering input from the specified reader.
+     * 
+     * @param rdr the reader which the returned reader should be filtering
+     * 
+     * @return a reader with the same configuration as this one, but
+     *         filtering input from the specified reader
+     */
     public Reader chain(Reader rdr);
 }

src/main/org/apache/tools/ant/filters/ClassConstants.java

@@ -60,28 +60,23 @@ import java.lang.reflect.Method;
 
 
 /**
- * Assemble the constants declared in a Java class in
- * key1=value1(line separator)key2=value2
- * format
- *
+ * Assembles the constants declared in a Java class in
+ * <code>key1=value1(line separator)key2=value2</code>
+ * format.
+ *<p>
  * Notes:
- * =====
- * 1. This filter uses the BCEL external toolkit.
- * 2. This assembles only those constants that are not created
- *    using the syntax new whatever().
- * 3. This assembles constants declared using the basic datatypes
- *    and String only.
- * 4. The access modifiers of the declared constants do not matter.
- *
- * Example:
- * =======
- *
- * &lt;classconstants/&gt;
- *
+ * <ol>
+ * <li>This filter uses the BCEL external toolkit.
+ * <li>This assembles only those constants that are not created
+ * using the syntax <code>new whatever()</code>
+ * <li>This assembles constants declared using the basic datatypes
+ * and String only.</li>
+ * <li>The access modifiers of the declared constants do not matter.</li>
+ *</ol>
+ * Example:<br>
+ * <pre>&lt;classconstants/&gt;</pre>
  * Or:
- *
- * &lt;filterreader classname=&quot;org.apache.tools.ant.filters.ClassConstants&quot;/&gt;
- *
+ * <pre>&lt;filterreader classname=&quot;org.apache.tools.ant.filters.ClassConstants&quot;/&gt;</pre>
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
 public final class ClassConstants
@@ -91,30 +86,39 @@ public final class ClassConstants
     private String queuedData = null;
 
     /** Helper Class to be invoked via reflection. */
-    private String JAVA_CLASS_HELPER =
+    private static final String JAVA_CLASS_HELPER =
         "org.apache.tools.ant.filters.util.JavaClassHelper";
 
     /**
-     * This constructor is a dummy constructor and is
-     * not meant to be used by any class other than Ant's
-     * introspection mechanism. This will close the filter
-     * that is created making it useless for further operations.
+     * Constructor for "dummy" instances.
+     * 
+     * @see BaseFilterReader#BaseFilterReader()
      */
     public ClassConstants() {
         super();
     }
 
     /**
-     * Create a new filtered reader.
+     * Creates a new filtered reader. The contents of the passed-in reader
+     * are expected to be the name of the class from which to produce a 
+     * list of constants.
      *
-     * @param in  a Reader object providing the underlying stream.
+     * @param in A Reader object providing the underlying stream.
+     *           Must not be <code>null</code>.
      */
     public ClassConstants(final Reader in) {
         super(in);
     }
 
     /**
-     * Read and assemble the constants declared in a class file.
+     * Reads and assembles the constants declared in a class file.
+     * 
+     * @return the next character in the list of constants, or -1
+     * if the end of the resulting stream has been reached
+     * 
+     * @exception IOException if the underlying stream throws an IOException
+     * during reading, or if the constants for the specified class cannot
+     * be read (for example due to the class not being found).
      */
     public final int read() throws IOException {
 
@@ -148,7 +152,7 @@ public final class ClassConstants
                         final Object[] args = {
                             bytes
                         };
-                        // getConstants is a staic method, no need to
+                        // getConstants is a static method, no need to
                         // pass in the object
                         final StringBuffer sb = (StringBuffer)
                                 getConstants.invoke(null, args);
@@ -174,8 +178,14 @@ public final class ClassConstants
     }
 
     /**
-     * Create a new ClassConstants using the passed in
+     * Creates a new ClassConstants using the passed in
      * Reader for instantiation.
+     * 
+     * @param rdr A Reader object providing the underlying stream.
+     *            Must not be <code>null</code>.
+     * 
+     * @return a new filter based on this configuration, but filtering
+     *         the specified reader
      */
     public final Reader chain(final Reader rdr) {
         ClassConstants newFilter = new ClassConstants(rdr);

src/main/org/apache/tools/ant/filters/ExpandProperties.java

@@ -59,17 +59,13 @@ import java.io.Reader;
 import org.apache.tools.ant.Project;
 
 /**
- * Expand Ant properties, if any, in the data.
- *
- * Example:
- * =======
- *
- * <expandproperties/>
- *
+ * Expands Ant properties, if any, in the data.
+ * <p>
+ * Example:<br>
+ * <pre>&lt;expandproperties/&gt;</pre>
  * Or:
- *
- * &lt;filterreader classname=&quot;org.apache.tools.ant.filters.ExpandProperties&quot;/&gt;
- *
+ * <pre>&lt;filterreader classname=&quot;org.apache.tools.ant.filters.ExpandProperties&quot;/&gt;</pre>
+ * 
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
 public final class ExpandProperties
@@ -79,26 +75,35 @@ public final class ExpandProperties
     private String queuedData = null;
 
     /**
-     * This constructor is a dummy constructor and is
-     * not meant to be used by any class other than Ant's
-     * introspection mechanism. This will close the filter
-     * that is created making it useless for further operations.
+     * Constructor for "dummy" instances.
+     * 
+     * @see BaseFilterReader#BaseFilterReader()
      */
     public ExpandProperties() {
         super();
     }
 
     /**
-     * Create a new filtered reader.
+     * Creates a new filtered reader.
      *
-     * @param in  a Reader object providing the underlying stream.
+     * @param in A Reader object providing the underlying stream.
+     *           Must not be <code>null</code>.
      */
     public ExpandProperties(final Reader in) {
         super(in);
     }
 
     /**
-     * Prefix lines with user defined prefix.
+     * Returns the next character in the filtered stream. The original
+     * stream is first read in fully, and the Ant properties are expanded.
+     * The results of this expansion are then queued so they can be read
+     * character-by-character.
+     * 
+     * @return the next character in the resulting stream, or -1
+     * if the end of the resulting stream has been reached
+     * 
+     * @exception IOException if the underlying stream throws an IOException
+     * during reading     
      */
     public final int read() throws IOException {
 
@@ -128,8 +133,14 @@ public final class ExpandProperties
     }
 
     /**
-     * Create a new PrefixLines using the passed in
+     * Creates a new ExpandProperties filter using the passed in
      * Reader for instantiation.
+     * 
+     * @param rdr A Reader object providing the underlying stream.
+     *            Must not be <code>null</code>.
+     * 
+     * @return a new filter based on this configuration, but filtering
+     *         the specified reader
      */
     public final Reader chain(final Reader rdr) {
         ExpandProperties newFilter = new ExpandProperties(rdr);

src/main/org/apache/tools/ant/filters/HeadFilter.java

@@ -59,54 +59,60 @@ import java.io.Reader;
 import org.apache.tools.ant.types.Parameter;
 
 /**
- * Read the first n lines (Default is first 10 lines)
- *
+ * Reads the first <code>n</code> lines of a stream.
+ * (Default is first 10 lines.)
+ * <p>
  * Example:
- * =======
- *
- * &lt;headfilter lines=&quot;3&quot;/&gt;
- *
+ * <pre>&lt;headfilter lines=&quot;3&quot;/&gt;</pre>
  * Or:
- *
- * &lt;filterreader classname=&quot;org.apache.tools.ant.filters.HeadFilter&quot;&gt;
+ * <pre>&lt;filterreader classname=&quot;org.apache.tools.ant.filters.HeadFilter&quot;&gt;
  *    &lt;param name=&quot;lines&quot; value=&quot;3&quot;/&gt;
- * &lt;/filterreader&gt;
+ * &lt;/filterreader&gt;</pre>
  *
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
 public final class HeadFilter
     extends BaseParamFilterReader
     implements ChainableReader {
-    /** Lines key to represent the number of lines to be returned. */
+    /** Parameter name for the number of lines to be returned. */
     private static final String LINES_KEY = "lines";
 
     /** Number of lines currently read in. */
     private long linesRead = 0;
 
-    /** Default number of lines returned. */
+    /** Number of lines to be returned in the filtered stream. */
     private long lines = 10;
 
     /**
-     * This constructor is a dummy constructor and is
-     * not meant to be used by any class other than Ant's
-     * introspection mechanism. This will close the filter
-     * that is created making it useless for further operations.
+     * Constructor for "dummy" instances.
+     * 
+     * @see BaseFilterReader#BaseFilterReader()
      */
     public HeadFilter() {
         super();
     }
 
     /**
-     * Create a new filtered reader.
+     * Creates a new filtered reader.
      *
-     * @param in  a Reader object providing the underlying stream.
+     * @param in A Reader object providing the underlying stream.
+     *           Must not be <code>null</code>.
      */
     public HeadFilter(final Reader in) {
         super(in);
     }
 
     /**
-     * Read the first n lines.
+     * Returns the next character in the filtered stream. If the desired
+     * number of lines have already been read, the resulting stream is
+     * effectively at an end. Otherwise, the next character from the 
+     * underlying stream is read and returned.
+     * 
+     * @return the next character in the resulting stream, or -1
+     * if the end of the resulting stream has been reached
+     * 
+     * @exception IOException if the underlying stream throws an IOException
+     * during reading     
      */
     public final int read() throws IOException {
         if (!getInitialized()) {
@@ -129,22 +135,32 @@ public final class HeadFilter
     }
 
     /**
-     * Set number of lines to be returned.
+     * Sets the number of lines to be returned in the filtered stream.
+     * 
+     * @param lines the number of lines to be returned in the filtered stream
      */
     public final void setLines(final long lines) {
         this.lines = lines;
     }
 
     /**
-     * Get number of lines to be returned.
+     * Returns the number of lines to be returned in the filtered stream.
+     * 
+     * @return the number of lines to be returned in the filtered stream
      */
     private final long getLines() {
         return lines;
     }
 
     /**
-     * Create a new HeadFilter using the passed in
+     * Creates a new HeadFilter using the passed in
      * Reader for instantiation.
+     * 
+     * @param rdr A Reader object providing the underlying stream.
+     *            Must not be <code>null</code>.
+     * 
+     * @return a new filter based on this configuration, but filtering
+     *         the specified reader
      */
     public final Reader chain(final Reader rdr) {
         HeadFilter newFilter = new HeadFilter(rdr);
@@ -154,7 +170,8 @@ public final class HeadFilter
     }
 
     /**
-     * Scan for the lines parameter.
+     * Scans the parameters list for the "lines" parameter and uses
+     * it to set the number of lines to be returned in the filtered stream.
      */
     private final void initialize() {
         Parameter[] params = getParameters();

src/main/org/apache/tools/ant/filters/LineContains.java

@@ -60,62 +60,72 @@ import java.util.Vector;
 import org.apache.tools.ant.types.Parameter;
 
 /**
- * Filter Reader to fetch only those lines that contain user specified
+ * Filter which includes only those lines that contain all the user-specified
  * strings.
  *
  * Example:
- * =======
  *
- * <linecontains>
+ * <pre>&lt;linecontains&gt;
  *   &lt;contains value=&quot;foo&quot;&gt;
  *   &lt;contains value=&quot;bar&quot;&gt;
- * &lt;/linecontains&gt;
+ * &lt;/linecontains&gt;</pre>
  *
  * Or:
  *
- * &lt;filterreader classname="org.apache.tools.ant.filters.LineContains"&gt;
+ * <pre>&lt;filterreader classname="org.apache.tools.ant.filters.LineContains"&gt;
  *    &lt;param type="contains" value="foo"/&gt;
  *    &lt;param type="contains" value="bar"/&gt;
- * &lt;/filterreader&gt;
+ * &lt;/filterreader&gt;</pre>
  *
- * This will fetch all those lines that contain foo and bar
+ * This will include only those lines that contain <code>foo</code> and 
+ * <code>bar</code>.
  *
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
 public final class LineContains
     extends BaseParamFilterReader
     implements ChainableReader {
-    /** contains key */
+    /** Parameter name for the words to filter on. */
     private static final String CONTAINS_KEY = "contains";
 
     /** Vector that holds the strings that input lines must contain. */
     private Vector contains = new Vector();
 
-    /** Currently read in line. */
+    /** 
+     * Remaining line to be read from this filter, or <code>null</code> if
+     * the next call to <code>read()</code> should read the original stream
+     * to find the next matching line.
+     */
     private String line = null;
 
     /**
-     * This constructor is a dummy constructor and is
-     * not meant to be used by any class other than Ant's
-     * introspection mechanism. This will close the filter
-     * that is created making it useless for further operations.
+     * Constructor for "dummy" instances.
+     * 
+     * @see BaseFilterReader#BaseFilterReader()
      */
     public LineContains() {
         super();
     }
 
     /**
-     * Create a new filtered reader.
+     * Creates a new filtered reader.
      *
-     * @param in  a Reader object providing the underlying stream.
+     * @param in A Reader object providing the underlying stream.
+     *           Must not be <code>null</code>.
      */
     public LineContains(final Reader in) {
         super(in);
     }
 
     /**
-     * Choose only those lines that contains
-     * user defined values.
+     * Returns the next character in the filtered stream, only including
+     * lines from the original stream which contain all of the specified words.
+     * 
+     * @return the next character in the resulting stream, or -1
+     * if the end of the resulting stream has been reached
+     * 
+     * @exception IOException if the underlying stream throws an IOException
+     * during reading     
      */
     public final int read() throws IOException {
         if (!getInitialized()) {
@@ -154,29 +164,48 @@ public final class LineContains
     }
 
     /**
-     * Add a contains element.
+     * Adds a <code>contains</code> element.
+     * 
+     * @param contains The <code>contains</code> element to add. 
+     *                 Must not be <code>null</code>.
      */
     public final void addConfiguredContains(final Contains contains) {
         this.contains.addElement(contains.getValue());
     }
 
     /**
-     * Set contains vector.
+     * Sets the vector of words which must be contained within a line read
+     * from the original stream in order for it to match this filter.
+     * 
+     * @param contains A vector of words which must be contained within a line
+     * in order for it to match in this filter. Must not be <code>null</code>.
      */
     private void setContains(final Vector contains) {
         this.contains = contains;
     }
 
     /**
-     * Get contains vector.
+     * Returns the vector of words which must be contained within a line read
+     * from the original stream in order for it to match this filter.
+     * 
+     * @return the vector of words which must be contained within a line read
+     * from the original stream in order for it to match this filter. The
+     * returned object is "live" - in other words, changes made to the
+     * returned object are mirrored in the filter.
      */
     private final Vector getContains() {
         return contains;
     }
 
     /**
-     * Create a new LineContains using the passed in
+     * Creates a new LineContains using the passed in
      * Reader for instantiation.
+     * 
+     * @param rdr A Reader object providing the underlying stream.
+     *            Must not be <code>null</code>.
+     * 
+     * @return a new filter based on this configuration, but filtering
+     *         the specified reader
      */
     public final Reader chain(final Reader rdr) {
         LineContains newFilter = new LineContains(rdr);
@@ -186,7 +215,7 @@ public final class LineContains
     }
 
     /**
-     * Parse params to add user defined contains strings.
+     * Parses the parameters to add user-defined contains strings.
      */
     private final void initialize() {
         Parameter[] params = getParameters();
@@ -208,14 +237,19 @@ public final class LineContains
         private String value;
 
         /**
-         * Set the contains string
+         * Sets the contains string
+         * 
+         * @param contains The contains string to set. 
+         *                 Must not be <code>null</code>.
          */
         public final void setValue(String contains) {
             value = contains;
         }
 
         /**
-         * Get the contains string
+         * Returns the contains string.
+         * 
+         * @return the contains string for this element
          */
         public final String getValue() {
             return value;

src/main/org/apache/tools/ant/filters/LineContainsRegExp.java

@@ -62,60 +62,69 @@ import org.apache.tools.ant.types.RegularExpression;
 import org.apache.tools.ant.util.regexp.Regexp;
 
 /**
- * Filter Reader to fetch only those lines that contain user specified
+ * Filter which includes only those lines that contain the user-specified
  * regular expression matching strings.
  *
  * Example:
- * =======
- *
- * <linecontainsregexp>
+ * <pre>&lt;linecontainsregexp&gt;
  *   &lt;regexp pattern=&quot;foo*&quot;&gt;
- * &lt;/linecontainsregexp&gt;
+ * &lt;/linecontainsregexp&gt;</pre>
  *
  * Or:
  *
- * &lt;filterreader classname=&quot;org.apache.tools.ant.filters.LineContainsRegExp&quot;&gt;
+ * <pre>&lt;filterreader classname=&quot;org.apache.tools.ant.filters.LineContainsRegExp&quot;&gt;
  *    &lt;param type=&quot;regexp&quot; value=&quot;foo*&quot;/&gt;
- * &lt;/filterreader&gt;
+ * &lt;/filterreader&gt;</pre>
  *
- * This will fetch all those lines that contain the pattern foo
+ * This will fetch all those lines that contain the pattern <code>foo</code>
  *
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
 public final class LineContainsRegExp
     extends BaseParamFilterReader
     implements ChainableReader {
-    /** contains key */
+    /** Parameter name for the regular expression to filter on. */
     private static final String REGEXP_KEY = "regexp";
 
-    /** Vector that holds the strings that input lines must contain. */
+    /** Vector that holds the expressions that input lines must contain. */
     private Vector regexps = new Vector();
 
-    /** Currently read in line. */
+    /** 
+     * Remaining line to be read from this filter, or <code>null</code> if
+     * the next call to <code>read()</code> should read the original stream
+     * to find the next matching line.
+     */
     private String line = null;
 
     /**
-     * This constructor is a dummy constructor and is
-     * not meant to be used by any class other than Ant's
-     * introspection mechanism. This will close the filter
-     * that is created making it useless for further operations.
+     * Constructor for "dummy" instances.
+     * 
+     * @see BaseFilterReader#BaseFilterReader()
      */
     public LineContainsRegExp() {
         super();
     }
 
     /**
-     * Create a new filtered reader.
+     * Creates a new filtered reader.
      *
-     * @param in  a Reader object providing the underlying stream.
+     * @param in A Reader object providing the underlying stream.
+     *           Must not be <code>null</code>.
      */
     public LineContainsRegExp(final Reader in) {
         super(in);
     }
 
     /**
-     * Choose only those lines that contains
-     * user defined values.
+     * Returns the next character in the filtered stream, only including
+     * lines from the original stream which match all of the specified
+     * regular expressions.
+     * 
+     * @return the next character in the resulting stream, or -1
+     * if the end of the resulting stream has been reached
+     * 
+     * @exception IOException if the underlying stream throws an IOException
+     * during reading     
      */
     public final int read() throws IOException {
         if (!getInitialized()) {
@@ -157,29 +166,51 @@ public final class LineContainsRegExp
     }
 
     /**
-     * Add a contains element.
+     * Adds a <code>regexp</code> element.
+     * 
+     * @param regExp The <code>regexp</code> element to add. 
+     *               Must not be <code>null</code>.
      */
     public final void addConfiguredRegexp(final RegularExpression regExp) {
         this.regexps.addElement(regExp);
     }
 
     /**
-     * Set regexps vector.
+     * Sets the vector of regular expressions which must be contained within 
+     * a line read from the original stream in order for it to match this 
+     * filter.
+     * 
+     * @param regexps A vector of regular expressions which must be contained 
+     * within a line in order for it to match in this filter. Must not be 
+     * <code>null</code>.
      */
     private void setRegexps(final Vector regexps) {
         this.regexps = regexps;
     }
 
     /**
-     * Get regexps vector.
+     * Returns the vector of regular expressions which must be contained within 
+     * a line read from the original stream in order for it to match this 
+     * filter.
+     * 
+     * @return the vector of regular expressions which must be contained within 
+     * a line read from the original stream in order for it to match this 
+     * filter. The returned object is "live" - in other words, changes made to 
+     * the returned object are mirrored in the filter.
      */
     private final Vector getRegexps() {
         return regexps;
     }
 
     /**
-     * Create a new LineContainsRegExp using the passed in
+     * Creates a new LineContainsRegExp using the passed in
      * Reader for instantiation.
+     * 
+     * @param rdr A Reader object providing the underlying stream.
+     *            Must not be <code>null</code>.
+     * 
+     * @return a new filter based on this configuration, but filtering
+     *         the specified reader
      */
     public final Reader chain(final Reader rdr) {
         LineContainsRegExp newFilter = new LineContainsRegExp(rdr);
@@ -189,7 +220,7 @@ public final class LineContainsRegExp
     }
 
     /**
-     * Parse params to add user defined contains strings.
+     * Parses parameters to add user defined regular expressions.
      */
     private final void initialize() {
         Parameter[] params = getParameters();

src/main/org/apache/tools/ant/filters/PrefixLines.java

@@ -59,25 +59,23 @@ import java.io.Reader;
 import org.apache.tools.ant.types.Parameter;
 
 /**
- * Attach a prefix to every line
+ * Attaches a prefix to every line.
  *
  * Example:
- * =======
- *
- * <prefixlines prefix="Foo"/>
+ * <pre>&lt;prefixlines prefix=&quot;Foo&quot;/&gt;</pre>
  *
  * Or:
  *
- * &lt;filterreader classname=&quot;org.apache.tools.ant.filters.PrefixLines&quot;&gt;
- *    &lt;param name=&quot;prefix&quot; value=&quot;Foo&quot;/&gt;
- * &lt;/filterreader&gt;
+ * <pre>&lt;filterreader classname=&quot;org.apache.tools.ant.filters.PrefixLines&quot;&gt;
+ *  &lt;param name=&quot;prefix&quot; value=&quot;Foo&quot;/&gt;
+ * &lt;/filterreader&gt;</pre>
  *
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
 public final class PrefixLines
     extends BaseParamFilterReader
     implements ChainableReader {
-    /** prefix key */
+    /** Parameter name for the prefix. */
     private static final String PREFIX_KEY = "prefix";
 
     /** The prefix to be used. */
@@ -87,26 +85,35 @@ public final class PrefixLines
     private String queuedData = null;
 
     /**
-     * This constructor is a dummy constructor and is
-     * not meant to be used by any class other than Ant's
-     * introspection mechanism. This will close the filter
-     * that is created making it useless for further operations.
+     * Constructor for "dummy" instances.
+     * 
+     * @see BaseFilterReader#BaseFilterReader()
      */
     public PrefixLines() {
         super();
     }
 
     /**
-     * Create a new filtered reader.
+     * Creates a new filtered reader.
      *
-     * @param in  a Reader object providing the underlying stream.
+     * @param in A Reader object providing the underlying stream.
+     *           Must not be <code>null</code>.
      */
     public PrefixLines(final Reader in) {
         super(in);
     }
 
     /**
-     * Prefix lines with user defined prefix.
+     * Returns the next character in the filtered stream. One line is read
+     * from the original input, and the prefix added. The resulting
+     * line is then used until it ends, at which point the next original line
+     * is read, etc.
+     * 
+     * @return the next character in the resulting stream, or -1
+     * if the end of the resulting stream has been reached
+     * 
+     * @exception IOException if the underlying stream throws an IOException
+     * during reading     
      */
     public final int read() throws IOException {
         if (!getInitialized()) {
@@ -141,22 +148,34 @@ public final class PrefixLines
     }
 
     /**
-     * Set the prefix
+     * Sets the prefix to add at the start of each input line.
+     * 
+     * @param prefix The prefix to add at the start of each input line.
+     *               May be <code>null</code>, in which case no prefix
+     *               is added.
      */
     public final void setPrefix(final String prefix) {
         this.prefix = prefix;
     }
 
     /**
-     * Get the prefix
+     * Returns the prefix which will be added at the start of each input line.
+     * 
+     * @return the prefix which will be added at the start of each input line
      */
     private final String getPrefix() {
         return prefix;
     }
 
     /**
-     * Create a new PrefixLines using the passed in
+     * Creates a new PrefixLines filter using the passed in
      * Reader for instantiation.
+     * 
+     * @param rdr A Reader object providing the underlying stream.
+     *            Must not be <code>null</code>.
+     * 
+     * @return a new filter based on this configuration, but filtering
+     *         the specified reader
      */
     public final Reader chain(final Reader rdr) {
         PrefixLines newFilter = new PrefixLines(rdr);
@@ -166,7 +185,7 @@ public final class PrefixLines
     }
 
     /**
-     * Initialize prefix if available from the param element.
+     * Initializes the prefix if it is available from the parameters.
      */
     private final void initialize() {
         Parameter[] params = getParameters();

src/main/org/apache/tools/ant/filters/ReplaceTokens.java

@@ -60,67 +60,73 @@ import java.util.Hashtable;
 import org.apache.tools.ant.types.Parameter;
 
 /**
- * Replace tokens with user supplied values
+ * Replaces tokens in the original input with user-supplied values
  *
- * Example Usage:
- * =============
+ * Example:
  *
- * <replacetokens begintoken="#" endtoken="#">
+ * <pre>&lt;replacetokens begintoken=&quot;#&quot; endtoken=&quot;#&quot;&gt;
  *   &lt;token key=&quot;DATE&quot; value=&quot;${TODAY}&quot;/&gt;
- * &lt;/replacetokens&gt;
+ * &lt;/replacetokens&gt;</pre>
  *
  * Or:
  *
- * &lt;filterreader classname="org.apache.tools.ant.filters.ReplaceTokens"&gt;
- *    &lt;param type="tokenchar" name="begintoken" value="#"/&gt;
- *    &lt;param type="tokenchar" name="endtoken" value="#"/&gt;
- *    &lt;param type="token" name="DATE" value="${TODAY}"/&gt;
- * &lt;/filterreader&gt;
+ * <pre>&lt;filterreader classname="org.apache.tools.ant.filters.ReplaceTokens"&gt;
+ *   &lt;param type="tokenchar" name="begintoken" value="#"/&gt;
+ *   &lt;param type="tokenchar" name="endtoken" value="#"/&gt;
+ *   &lt;param type="token" name="DATE" value="${TODAY}"/&gt;
+ * &lt;/filterreader&gt;</pre>
  *
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
 public final class ReplaceTokens
     extends BaseParamFilterReader
     implements ChainableReader {
-    /** Default begin token character. */
+    /** Default "begin token" character. */
     private static final char DEFAULT_BEGIN_TOKEN = '@';
 
-    /** Default end token character. */
+    /** Default "end token" character. */
     private static final char DEFAULT_END_TOKEN = '@';
 
     /** Data that must be read from, if not null. */
     private String queuedData = null;
 
-    /** Hashtable to hold the replacee-replacer pairs. */
+    /** Hashtable to hold the replacee-replacer pairs (String to String). */
     private Hashtable hash = new Hashtable();
 
-    /** Begin token. */
+    /** Character marking the beginning of a token. */
     private char beginToken = DEFAULT_BEGIN_TOKEN;
 
-    /** End token. */
+    /** Character marking the end of a token. */
     private char endToken = DEFAULT_END_TOKEN;
 
     /**
-     * This constructor is a dummy constructor and is
-     * not meant to be used by any class other than Ant's
-     * introspection mechanism. This will close the filter
-     * that is created making it useless for further operations.
+     * Constructor for "dummy" instances.
+     * 
+     * @see BaseFilterReader#BaseFilterReader()
      */
     public ReplaceTokens() {
         super();
     }
 
     /**
-     * Create a new filtered reader.
+     * Creates a new filtered reader.
      *
-     * @param in  a Reader object providing the underlying stream.
+     * @param in A Reader object providing the underlying stream.
+     *           Must not be <code>null</code>.
      */
     public ReplaceTokens(final Reader in) {
         super(in);
     }
 
     /**
-     * Replace tokens with values.
+     * Returns the next character in the filtered stream, replacing tokens
+     * from the original stream.
+     * 
+     * @return the next character in the resulting stream, or -1
+     * if the end of the resulting stream has been reached
+     * 
+     * @exception IOException if the underlying stream throws an IOException
+     * during reading     
      */
     public final int read() throws IOException {
         if (!getInitialized()) {
@@ -169,57 +175,80 @@ public final class ReplaceTokens
     }
 
     /**
-     * Set begin token.
+     * Sets the "begin token" character.
+     * 
+     * @param beginToken the character used to denote the beginning of a token
      */
     public final void setBeginToken(final char beginToken) {
         this.beginToken = beginToken;
     }
 
     /**
-     * Get begin token.
+     * Returns the "begin token" character.
+     * 
+     * @return the character used to denote the beginning of a token
      */
     private final char getBeginToken() {
         return beginToken;
     }
 
     /**
-     * Set end token.
+     * Sets the "end token" character.
+     * 
+     * @param endToken the character used to denote the end of a token
      */
     public final void setEndToken(final char endToken) {
         this.endToken = endToken;
     }
 
     /**
-     * Get begin token.
+     * Returns the "end token" character.
+     * 
+     * @return the character used to denote the end of a token
      */
     private final char getEndToken() {
         return endToken;
     }
 
     /**
-     * Add a token element.
+     * Adds a token element to the map of tokens to replace.
+     * 
+     * @param token The token to add to the map of replacements.
+     *              Must not be <code>null</code>.
      */
     public final void addConfiguredToken(final Token token) {
         hash.put(token.getKey(), token.getValue());
     }
 
     /**
-     * Set the tokens.
+     * Sets the map of tokens to replace.
+     * 
+     * @param hash A map (String->String) of token keys to replacement
+     * values. Must not be <code>null</code>.
      */
     private void setTokens(final Hashtable hash) {
         this.hash = hash;
     }
 
     /**
-     * Get the tokens.
+     * Returns the map of tokens which will be replaced.
+     * 
+     * @return a map (String->String) of token keys to replacement
+     * values
      */
     private final Hashtable getTokens() {
         return hash;
     }
 
     /**
-     * Create a new ReplaceTokens using the passed in
+     * Creates a new ReplaceTokens using the passed in
      * Reader for instantiation.
+     * 
+     * @param rdr A Reader object providing the underlying stream.
+     *            Must not be <code>null</code>.
+     * 
+     * @return a new filter based on this configuration, but filtering
+     *         the specified reader
      */
     public final Reader chain(final Reader rdr) {
         ReplaceTokens newFilter = new ReplaceTokens(rdr);
@@ -231,7 +260,7 @@ public final class ReplaceTokens
     }
 
     /**
-     * Initialize tokens and load the replacee-replacer hashtable.
+     * Initializes tokens and loads the replacee-replacer hashtable.
      */
     private final void initialize() {
         Parameter[] params = getParameters();
@@ -261,35 +290,43 @@ public final class ReplaceTokens
      */
     public static class Token {
 
-        /** token key */
+        /** Token key */
         private String key;
 
-        /** token value */
+        /** Token value */
         private String value;
 
         /**
-         * Set the token key
+         * Sets the token key
+         * 
+         * @param key The key for this token. Must not be <code>null</code>.
          */
         public final void setKey(String key) {
             this.key = key;
         }
 
         /**
-         * Set the token value
+         * Sets the token value
+         * 
+         * @param value The value for this token. Must not be <code>null</code>.
          */
         public final void setValue(String value) {
             this.value = value;
         }
 
         /**
-         * Get the token key
+         * Returns the key for this token.
+         * 
+         * @return the key for this token
          */
         public final String getKey() {
             return key;
         }
 
         /**
-         * Get the token value
+         * Returns the value for this token.
+         * 
+         * @return the value for this token
          */
         public final String getValue() {
             return value;

src/main/org/apache/tools/ant/filters/StringInputStream.java

@@ -58,38 +58,53 @@ import java.io.InputStream;
 import java.io.StringReader;
 
 /**
- * Wrap a String as an InputStream
+ * Wraps a String as an InputStream. Note that data will be lost for
+ * characters not in ISO Latin 1, as a simple char->byte mapping is assumed.
  *
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
 public class StringInputStream
     extends InputStream {
-    /** Source string is stored as a StringReader */
+    /** Source string, stored as a StringReader */
     private StringReader in;
 
     /**
-     * Compose a stream from a String
+     * Composes a stream from a String
+     * 
+     * @param source The string to read from. Must not be <code>null</code>.
      */
     public StringInputStream(String source) {
         in = new StringReader(source);
     }
 
     /**
-     * Read from the Stringreader
+     * Reads from the Stringreader, returning the same value. Note that
+     * data will be lost for characters not in ISO Latin 1. Clients
+     * assuming a return value in the range -1 to 255 may even fail on
+     * such input.
+     * 
+     * @return the value of the next character in the StringReader
+     * 
+     * @exception IOException if the original StringReader fails to be read
      */
     public int read() throws IOException {
         return in.read();
     }
 
     /**
-     * Close the Stringreader
+     * Closes the Stringreader.
+     * 
+     * @exception IOException if the original StringReader fails to be closed
      */
     public void close() throws IOException {
         in.close();
     }
 
     /**
-     * Mark the read limit of the StringReader
+     * Marks the read limit of the StringReader.
+     * 
+     * @param limit the maximum limit of bytes that can be read before the 
+     *              mark position becomes invalid
      */
     public synchronized void mark(final int limit) {
         try {
@@ -100,7 +115,9 @@ public class StringInputStream
     }
 
     /**
-     * Reset the StringReader.
+     * Resets the StringReader.
+     * 
+     * @exception IOException if the StringReader fails to be reset
      */
     public synchronized void reset() throws IOException {
         in.reset();

src/main/org/apache/tools/ant/filters/StripJavaComments.java

@@ -57,8 +57,8 @@ import java.io.IOException;
 import java.io.Reader;
 
 /**
- * This is a java comment and string stripper reader that filters
- * these lexical tokens out for purposes of simple Java parsing.
+ * This is a Java comment and string stripper reader that filters
+ * those lexical tokens out for purposes of simple Java parsing.
  * (if you have more complex Java parsing needs, use a real lexer).
  * Since this class heavily relies on the single char read function,
  * you are reccomended to make it work on top of a buffered reader.
@@ -66,31 +66,47 @@ import java.io.Reader;
 public final class StripJavaComments
     extends BaseFilterReader
     implements ChainableReader {
+        
+    /** 
+     * The read-ahead character, used for effectively pushing a single
+     * character back. -1 indicates that no character is in the buffer.
+     */
     private int readAheadCh = -1;
 
+    /** 
+     * Whether or not the parser is currently in the middle of a string
+     * literal.
+     */
     private boolean inString = false;
 
     /**
-     * This constructor is a dummy constructor and is
-     * not meant to be used by any class other than Ant's
-     * introspection mechanism. This will close the filter
-     * that is created making it useless for further operations.
+     * Constructor for "dummy" instances.
+     * 
+     * @see BaseFilterReader#BaseFilterReader()
      */
     public StripJavaComments() {
         super();
     }
 
     /**
-     * Create a new filtered reader.
+     * Creates a new filtered reader.
      *
-     * @param in  a Reader object providing the underlying stream.
+     * @param in A Reader object providing the underlying stream.
+     *           Must not be <code>null</code>.
      */
     public StripJavaComments(final Reader in) {
         super(in);
     }
 
     /**
-     * Filter out Java Style comments
+     * Returns the next character in the filtered stream, not including
+     * Java comments.
+     * 
+     * @return the next character in the resulting stream, or -1
+     * if the end of the resulting stream has been reached
+     * 
+     * @exception IOException if the underlying stream throws an IOException
+     * during reading     
      */
     public final int read() throws IOException {
         int ch = -1;
@@ -137,9 +153,16 @@ public final class StripJavaComments
     }
 
     /**
-     * Create a new StripJavaComments object using the passed in
+     * Creates a new StripJavaComments using the passed in
      * Reader for instantiation.
+     * 
+     * @param rdr A Reader object providing the underlying stream.
+     *            Must not be <code>null</code>.
+     * 
+     * @return a new filter based on this configuration, but filtering
+     *         the specified reader
      */
+
     public final Reader chain(final Reader rdr) {
         StripJavaComments newFilter = new StripJavaComments(rdr);
         return newFilter;

src/main/org/apache/tools/ant/filters/StripLineBreaks.java

@@ -60,12 +60,14 @@ import org.apache.tools.ant.types.Parameter;
 
 /**
  * Filter to flatten the stream to a single line.
+ * 
+ * Example:
  *
- * <striplinebreaks/>
+ * <pre>&lt;striplinebreaks/&gt;</pre>
  *
  * Or:
  *
- * &lt;filterreader classname=&quot;org.apache.tools.ant.filters.StripLineBreaks&quot;/&gt;
+ * <pre>&lt;filterreader classname=&quot;org.apache.tools.ant.filters.StripLineBreaks&quot;/&gt;</pre>
  *
  * @author Steve Loughran
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
@@ -74,43 +76,45 @@ public final class StripLineBreaks
     extends BaseParamFilterReader
     implements ChainableReader {
     /**
-     * Linebreaks. What do to on funny IBM mainframes with odd line endings?
+     * Line-breaking characters.
+     * What should we do on funny IBM mainframes with odd line endings?
      */
     private static final String DEFAULT_LINE_BREAKS = "\r\n";
 
-    /**
-     * Linebreaks key that can be set via param element of
-     * AntFilterReader
-     */
+    /** Parameter name for the line-breaking characters parameter. */
     private static final String LINE_BREAKS_KEY = "linebreaks";
 
-
-    /** Holds the characters that are recognized as line breaks. */
+    /** The characters that are recognized as line breaks. */
     private String lineBreaks = DEFAULT_LINE_BREAKS;
 
     /**
-     * This constructor is a dummy constructor and is
-     * not meant to be used by any class other than Ant's
-     * introspection mechanism. This will close the filter
-     * that is created making it useless for further operations.
+     * Constructor for "dummy" instances.
+     * 
+     * @see BaseFilterReader#BaseFilterReader()
      */
     public StripLineBreaks() {
         super();
     }
 
     /**
-     * Create a new filtered reader.
+     * Creates a new filtered reader.
      *
-     * @param in  a Reader object providing the underlying stream.
+     * @param in A Reader object providing the underlying stream.
+     *           Must not be <code>null</code>.
      */
     public StripLineBreaks(final Reader in) {
         super(in);
     }
 
     /**
-     * If the character that is being read in is a
-     * line break character, ignore it and move on to the
-     * next one.
+     * Returns the next character in the filtered stream, only including
+     * characters not in the set of line-breaking characters.
+     * 
+     * @return the next character in the resulting stream, or -1
+     * if the end of the resulting stream has been reached
+     * 
+     * @exception IOException if the underlying stream throws an IOException
+     * during reading     
      */
     public final int read() throws IOException {
         if (!getInitialized()) {
@@ -130,22 +134,34 @@ public final class StripLineBreaks
     }
 
     /**
-     * Set the line break characters.
+     * Sets the line-breaking characters.
+     * 
+     * @param lineBreaks A String containing all the characters to be
+     *                   considered as line-breaking.
      */
     public final void setLineBreaks(final String lineBreaks) {
         this.lineBreaks = lineBreaks;
     }
 
     /**
-     * Get the line breaks characters
+     * Returns the line-breaking characters as a String.
+     * 
+     * @return a String containing all the characters considered as 
+     *         line-breaking
      */
     private final String getLineBreaks() {
         return lineBreaks;
     }
 
     /**
-     * Create a new StripLineBreaks object using the passed in
+     * Creates a new StripLineBreaks using the passed in
      * Reader for instantiation.
+     * 
+     * @param rdr A Reader object providing the underlying stream.
+     *            Must not be <code>null</code>.
+     * 
+     * @return a new filter based on this configuration, but filtering
+     *         the specified reader
      */
     public final Reader chain(final Reader rdr) {
         StripLineBreaks newFilter = new StripLineBreaks(rdr);
@@ -155,7 +171,7 @@ public final class StripLineBreaks
     }
 
     /**
-     * Line break characters set using the param element.
+     * Parses the parameters to set the line-breaking characters.
      */
     private final void initialize() {
         String userDefinedLineBreaks = null;

src/main/org/apache/tools/ant/filters/StripLineComments.java

@@ -60,65 +60,71 @@ import java.util.Vector;
 import org.apache.tools.ant.types.Parameter;
 
 /**
- * This is a line comment stripper reader
+ * This filter strips line comments.
  *
  * Example:
- * =======
  *
- * <striplinecomments>
+ * <pre>&lt;striplinecomments&gt;
  *   &lt;comment value=&quot;#&quot;/&gt;
  *   &lt;comment value=&quot;--&quot;/&gt;
  *   &lt;comment value=&quot;REM &quot;/&gt;
  *   &lt;comment value=&quot;rem &quot;/&gt;
  *   &lt;comment value=&quot;//&quot;/&gt;
- * &lt;/striplinecomments&gt;
+ * &lt;/striplinecomments&gt;</pre>
  *
  * Or:
  *
- * &lt;filterreader classname=&quot;org.apache.tools.ant.filters.StripLineComments&quot;&gt;
- *    &lt;param type=&quot;comment&quot; value="#&quot;/&gt;
- *    &lt;param type=&quot;comment&quot; value=&quot;--&quot;/&gt;
- *    &lt;param type=&quot;comment&quot; value=&quot;REM &quot;/&gt;
- *    &lt;param type=&quot;comment&quot; value=&quot;rem &quot;/&gt;
- *    &lt;param type=&quot;comment&quot; value=&quot;//&quot;/&gt;
- * &lt;/filterreader&gt;
+ * <pre>&lt;filterreader classname=&quot;org.apache.tools.ant.filters.StripLineComments&quot;&gt;
+ *   &lt;param type=&quot;comment&quot; value="#&quot;/&gt;
+ *   &lt;param type=&quot;comment&quot; value=&quot;--&quot;/&gt;
+ *   &lt;param type=&quot;comment&quot; value=&quot;REM &quot;/&gt;
+ *   &lt;param type=&quot;comment&quot; value=&quot;rem &quot;/&gt;
+ *   &lt;param type=&quot;comment&quot; value=&quot;//&quot;/&gt;
+ * &lt;/filterreader&gt;</pre>
  *
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
 public final class StripLineComments
     extends BaseParamFilterReader
     implements ChainableReader {
-    /** The type that param recognizes to set the comments. */
+    /** Parameter name for the comment prefix. */
     private static final String COMMENTS_KEY = "comment";
 
-    /** Vector that holds comments. */
+    /** Vector that holds the comment prefixes. */
     private Vector comments = new Vector();
 
     /** The line that has been read ahead. */
     private String line = null;
 
     /**
-     * This constructor is a dummy constructor and is
-     * not meant to be used by any class other than Ant's
-     * introspection mechanism. This will close the filter
-     * that is created making it useless for further operations.
+     * Constructor for "dummy" instances.
+     * 
+     * @see BaseFilterReader#BaseFilterReader()
      */
     public StripLineComments() {
         super();
     }
 
     /**
-     * Create a new filtered reader.
+     * Creates a new filtered reader.
      *
-     * @param in  a Reader object providing the underlying stream.
+     * @param in A Reader object providing the underlying stream.
+     *           Must not be <code>null</code>.
      */
     public StripLineComments(final Reader in) {
         super(in);
     }
 
     /**
-     * Read in line by line; Ignore line if it
-     * begins with a comment string.
+     * Returns the next character in the filtered stream, only including
+     * lines from the original stream which don't start with any of the 
+     * specified comment prefixes.
+     * 
+     * @return the next character in the resulting stream, or -1
+     * if the end of the resulting stream has been reached
+     * 
+     * @exception IOException if the underlying stream throws an IOException
+     * during reading     
      */
     public final int read() throws IOException {
         if (!getInitialized()) {
@@ -156,29 +162,43 @@ public final class StripLineComments
     }
 
     /**
-     * Add the Comment element.
+     * Adds a <code>comment</code> element to the list of prefixes.
+     * 
+     * @param comment The <code>comment</code> element to add to the
+     * list of comment prefixes to strip. Must not be <code>null</code>.
      */
     public final void addConfiguredComment(final Comment comment) {
         comments.addElement(comment.getValue());
     }
 
     /**
-     * Set the comments vector.
+     * Sets the list of comment prefixes to strip.
+     * 
+     * @param comments A list of strings, each of which is a prefix
+     * for a comment line. Must not be <code>null</code>.
      */
     private void setComments(final Vector comments) {
         this.comments = comments;
     }
 
     /**
-     * Get the comments vector.
+     * Returns the list of comment prefixes to strip.
+     * 
+     * @return the list of comment prefixes to strip.
      */
     private final Vector getComments() {
         return comments;
     }
 
     /**
-     * Create a new StripLineComments object using the passed in
+     * Creates a new StripLineComments using the passed in
      * Reader for instantiation.
+     * 
+     * @param rdr A Reader object providing the underlying stream.
+     *            Must not be <code>null</code>.
+     * 
+     * @return a new filter based on this configuration, but filtering
+     *         the specified reader
      */
     public final Reader chain(final Reader rdr) {
         StripLineComments newFilter = new StripLineComments(rdr);
@@ -188,7 +208,7 @@ public final class StripLineComments
     }
 
     /**
-     * Comments set using the param element.
+     * Parses the parameters to set the comment prefixes.
      */
     private final void initialize() {
         Parameter[] params = getParameters();
@@ -202,22 +222,27 @@ public final class StripLineComments
     }
 
     /**
-     * The class that holds a comment.
+     * The class that holds a comment representation.
      */
     public static class Comment {
 
-        /** The comment*/
+        /** The prefix for a line comment. */
         private String value;
 
         /**
-         * Set the comment.
+         * Sets the prefix for this type of line comment.
+         * 
+         * @param comment The prefix for a line comment of this type.
+         * Must not be <code>null</code>.
          */
         public final void setValue(String comment) {
             value = comment;
         }
 
         /**
-         * Get the comment.
+         * Returns the prefix for this type of line comment.
+         * 
+         * @return the prefix for this type of line comment.
          */
         public final String getValue() {
             return value;

src/main/org/apache/tools/ant/filters/TabsToSpaces.java

@@ -61,55 +61,61 @@ import org.apache.tools.ant.types.Parameter;
 /**
  * Converts tabs to spaces.
  *
- * Example Usage:
- * =============
+ * Example:
  *
- * <tabtospaces tablength="8"/>
+ * <pre>&lt;tabtospaces tablength=&quot;8&quot;/&gt;</pre>
  *
  * Or:
  *
- * <filterreader classname=&quot;org.apache.tools.ant.filters.TabsToSpaces&quot;>
- *    <param name=&quot;tablength&quot; value=&quot;8&quot;/>
- * </filterreader>
+ * <pre>&lt;filterreader classname=&quot;org.apache.tools.ant.filters.TabsToSpaces&quot;&gt;
+ *   &lt;param name=&quot;tablength&quot; value=&quot;8&quot;/&gt;
+ * &lt;/filterreader&gt;</pre>
  *
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
 public final class TabsToSpaces
     extends BaseParamFilterReader
     implements ChainableReader {
-    /** The default tab length is 8 */
+    /** The default tab length. */
     private static final int DEFAULT_TAB_LENGTH = 8;
 
-    /** The name that param recognizes to set the tablength. */
+    /** Parameter name for the length of a tab. */
     private static final String TAB_LENGTH_KEY = "tablength";
 
-    /** Default tab length. */
+    /** Tab length in this filter. */
     private int tabLength = DEFAULT_TAB_LENGTH;
 
-    /** How many more spaces must be returned to replace a tab? */
+    /** The number of spaces still to be read to represent the last-read tab. */
     private int spacesRemaining = 0;
 
     /**
-     * This constructor is a dummy constructor and is
-     * not meant to be used by any class other than Ant's
-     * introspection mechanism. This will close the filter
-     * that is created making it useless for further operations.
+     * Constructor for "dummy" instances.
+     * 
+     * @see BaseFilterReader#BaseFilterReader()
      */
     public TabsToSpaces() {
         super();
     }
 
     /**
-     * Create a new filtered reader.
+     * Creates a new filtered reader.
      *
-     * @param in  a Reader object providing the underlying stream.
+     * @param in A Reader object providing the underlying stream.
+     *           Must not be <code>null</code>.
      */
     public TabsToSpaces(final Reader in) {
         super(in);
     }
 
     /**
-     * Convert tabs with spaces
+     * Returns the next character in the filtered stream, converting tabs
+     * to the specified number of spaces.
+     * 
+     * @return the next character in the resulting stream, or -1
+     * if the end of the resulting stream has been reached
+     * 
+     * @exception IOException if the underlying stream throws an IOException
+     * during reading     
      */
     public final int read() throws IOException {
         if (!getInitialized()) {
@@ -133,22 +139,32 @@ public final class TabsToSpaces
     }
 
     /**
-     * Set the tab length.
+     * Sets the tab length.
+     * 
+     * @param tabLength the number of spaces to be used when converting a tab.
      */
     public final void setTablength(final int tabLength) {
         this.tabLength = tabLength;
     }
 
     /**
-     * Get the tab length
+     * Returns the tab length.
+     * 
+     * @return the number of spaces used when converting a tab
      */
     private final int getTablength() {
         return tabLength;
     }
 
     /**
-     * Create a new TabsToSpaces object using the passed in
+     * Creates a new TabsToSpaces using the passed in
      * Reader for instantiation.
+     * 
+     * @param rdr A Reader object providing the underlying stream.
+     *            Must not be <code>null</code>.
+     * 
+     * @return a new filter based on this configuration, but filtering
+     *         the specified reader
      */
     public final Reader chain(final Reader rdr) {
         TabsToSpaces newFilter = new TabsToSpaces(rdr);
@@ -158,7 +174,7 @@ public final class TabsToSpaces
     }
 
     /**
-     * Initialize tokens
+     * Parses the parameters to set the tab length.
      */
     private final void initialize() {
         Parameter[] params = getParameters();

src/main/org/apache/tools/ant/filters/TailFilter.java

@@ -59,31 +59,30 @@ import java.io.Reader;
 import org.apache.tools.ant.types.Parameter;
 
 /**
- * Read the last n lines.  Default is last 10 lines.
+ * Reads the last <code>n</code> lines of a stream. (Default is last10 lines.)
  *
  * Example:
- * =======
  *
- * &lt;tailfilter lines=&quot;3&quot;/&gt;
+ * <pre>&lt;tailfilter lines=&quot;3&quot;/&gt;</pre>
  *
  * Or:
  *
- * &lt;filterreader classname=&quot;org.apache.tools.ant.filters.TailFilter&quot;&gt;
- *    &lt;param name=&quot;lines&quot; value=&quot;3&quot;/&gt;
- * &lt;/filterreader&gt;
+ * <pre>&lt;filterreader classname=&quot;org.apache.tools.ant.filters.TailFilter&quot;&gt;
+ *   &lt;param name=&quot;lines&quot; value=&quot;3&quot;/&gt;
+ * &lt;/filterreader&gt;</pre>
  *
  * @author <a href="mailto:umagesh@apache.org">Magesh Umasankar</a>
  */
 public final class TailFilter
     extends BaseParamFilterReader
     implements ChainableReader {
-    /** The name that param recognizes to set the number of lines. */
+    /** Parameter name for the number of lines to be returned. */
     private static final String LINES_KEY = "lines";
 
     /** Number of lines currently read in. */
     private long linesRead = 0;
 
-    /** Default number of lines returned. */
+    /** Number of lines to be returned in the filtered stream. */
     private long lines = 10;
 
     /** Buffer to hold in characters read ahead. */
@@ -92,34 +91,43 @@ public final class TailFilter
     /** The character position that has been returned from the buffer. */
     private int returnedCharPos = -1;
 
-    /** Has read ahead been completed? */
+    /** Whether or not read-ahead been completed. */
     private boolean completedReadAhead = false;
 
     /** Current index position on the buffer. */
     private int bufferPos = 0;
 
     /**
-     * This constructor is a dummy constructor and is
-     * not meant to be used by any class other than Ant's
-     * introspection mechanism. This will close the filter
-     * that is created making it useless for further operations.
+     * Constructor for "dummy" instances.
+     * 
+     * @see BaseFilterReader#BaseFilterReader()
      */
     public TailFilter() {
         super();
     }
 
     /**
-     * Create a new filtered reader.
+     * Creates a new filtered reader.
      *
-     * @param in  a Reader object providing the underlying stream.
+     * @param in A Reader object providing the underlying stream.
+     *           Must not be <code>null</code>.
      */
     public TailFilter(final Reader in) {
         super(in);
     }
 
     /**
-     * Read ahead and keep in buffer last n lines only at any given
-     * point.  Grow buffer as needed.
+     * Returns the next character in the filtered stream. If the read-ahead
+     * has been completed, the next character in the buffer is returned.
+     * Otherwise, the stream is read to the end and buffered (with the buffer
+     * growing as necessary), then the appropriate position in the buffer is
+     * set to read from.
+     * 
+     * @return the next character in the resulting stream, or -1
+     * if the end of the resulting stream has been reached
+     * 
+     * @exception IOException if the underlying stream throws an IOException
+     * during reading     
      */
     public final int read() throws IOException {
         if (!getInitialized()) {
@@ -176,22 +184,32 @@ public final class TailFilter
     }
 
     /**
-     * Set number of lines to be returned.
+     * Sets the number of lines to be returned in the filtered stream.
+     * 
+     * @param lines the number of lines to be returned in the filtered stream
      */
     public final void setLines(final long lines) {
         this.lines = lines;
     }
 
     /**
-     * Get number of lines to be returned.
+     * Returns the number of lines to be returned in the filtered stream.
+     * 
+     * @return the number of lines to be returned in the filtered stream
      */
     private final long getLines() {
         return lines;
     }
 
     /**
-     * Create a new TailFilter using the passed in
+     * Creates a new TailFilter using the passed in
      * Reader for instantiation.
+     * 
+     * @param rdr A Reader object providing the underlying stream.
+     *            Must not be <code>null</code>.
+     * 
+     * @return a new filter based on this configuration, but filtering
+     *         the specified reader
      */
     public final Reader chain(final Reader rdr) {
         TailFilter newFilter = new TailFilter(rdr);
@@ -201,7 +219,8 @@ public final class TailFilter
     }
 
     /**
-     * Scan for the lines parameter.
+     * Scans the parameters list for the "lines" parameter and uses
+     * it to set the number of lines to be returned in the filtered stream.
      */
     private final void initialize() {
         Parameter[] params = getParameters();