ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jsk...@apache.org
Subject cvs commit: jakarta-ant/src/main/org/apache/tools/ant/filters ChainableReader.java TabsToSpaces.java StripLineBreaks.java ClassConstants.java PrefixLines.java LineContains.java LineContainsRegExp.java StripLineComments.java StringInputStream.java ExpandProperties.java HeadFilter.java TailFilter.java BaseParamFilterReader.java BaseFilterReader.java StripJavaComments.java ReplaceTokens.java
Date Tue, 30 Apr 2002 10:32:03 GMT
jskeet      02/04/30 03:32:02

  Modified:    src/main/org/apache/tools/ant/filters ChainableReader.java
                        TabsToSpaces.java StripLineBreaks.java
                        ClassConstants.java PrefixLines.java
                        LineContains.java LineContainsRegExp.java
                        StripLineComments.java StringInputStream.java
                        ExpandProperties.java HeadFilter.java
                        TailFilter.java BaseParamFilterReader.java
                        BaseFilterReader.java StripJavaComments.java
                        ReplaceTokens.java
  Log:
  Fix-up of JavaDocs for filters (and a couple of style fixes too).
  
  Revision  Changes    Path
  1.3       +10 -1     jakarta-ant/src/main/org/apache/tools/ant/filters/ChainableReader.java
  
  Index: ChainableReader.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/filters/ChainableReader.java,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- ChainableReader.java	12 Apr 2002 13:26:50 -0000	1.2
  +++ ChainableReader.java	30 Apr 2002 10:32:01 -0000	1.3
  @@ -56,10 +56,19 @@
   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);
   }
  
  
  
  1.4       +37 -21    jakarta-ant/src/main/org/apache/tools/ant/filters/TabsToSpaces.java
  
  Index: TabsToSpaces.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/filters/TabsToSpaces.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- TabsToSpaces.java	15 Apr 2002 13:36:16 -0000	1.3
  +++ TabsToSpaces.java	30 Apr 2002 10:32:01 -0000	1.4
  @@ -61,55 +61,61 @@
   /**
    * Converts tabs to spaces.
    *
  - * Example Usage:
  - * =============
  + * Example:
    *
  - * &lt;tabtospaces tablength=&quot;8&quot;/&gt;
  + * <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 @@
       }
   
       /**
  -     * 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 @@
       }
   
       /**
  -     * Initialize tokens
  +     * Parses the parameters to set the tab length.
        */
       private final void initialize() {
           Parameter[] params = getParameters();
  
  
  
  1.4       +38 -22    jakarta-ant/src/main/org/apache/tools/ant/filters/StripLineBreaks.java
  
  Index: StripLineBreaks.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/filters/StripLineBreaks.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- StripLineBreaks.java	15 Apr 2002 13:36:16 -0000	1.3
  +++ StripLineBreaks.java	30 Apr 2002 10:32:01 -0000	1.4
  @@ -60,12 +60,14 @@
   
   /**
    * Filter to flatten the stream to a single line.
  + * 
  + * Example:
    *
  - * &lt;striplinebreaks/&gt;
  + * <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 @@
       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 @@
       }
   
       /**
  -     * 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 @@
       }
   
       /**
  -     * Line break characters set using the param element.
  +     * Parses the parameters to set the line-breaking characters.
        */
       private final void initialize() {
           String userDefinedLineBreaks = null;
  
  
  
  1.5       +40 -30    jakarta-ant/src/main/org/apache/tools/ant/filters/ClassConstants.java
  
  Index: ClassConstants.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/filters/ClassConstants.java,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- ClassConstants.java	15 Apr 2002 13:36:16 -0000	1.4
  +++ ClassConstants.java	30 Apr 2002 10:32:01 -0000	1.5
  @@ -60,28 +60,23 @@
   
   
   /**
  - * 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 @@
       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 @@
                           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 @@
       }
   
       /**
  -     * 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);
  
  
  
  1.4       +38 -19    jakarta-ant/src/main/org/apache/tools/ant/filters/PrefixLines.java
  
  Index: PrefixLines.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/filters/PrefixLines.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- PrefixLines.java	15 Apr 2002 13:36:16 -0000	1.3
  +++ PrefixLines.java	30 Apr 2002 10:32:01 -0000	1.4
  @@ -59,25 +59,23 @@
   import org.apache.tools.ant.types.Parameter;
   
   /**
  - * Attach a prefix to every line
  + * Attaches a prefix to every line.
    *
    * Example:
  - * =======
  - *
  - * &lt;prefixlines prefix=&quot;Foo&quot;/&gt;
  + * <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 @@
       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 @@
       }
   
       /**
  -     * 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 @@
       }
   
       /**
  -     * 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();
  
  
  
  1.4       +58 -24    jakarta-ant/src/main/org/apache/tools/ant/filters/LineContains.java
  
  Index: LineContains.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/filters/LineContains.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- LineContains.java	15 Apr 2002 13:36:16 -0000	1.3
  +++ LineContains.java	30 Apr 2002 10:32:01 -0000	1.4
  @@ -60,62 +60,72 @@
   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:
  - * =======
    *
  - * &lt;linecontains&gt;
  + * <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 @@
       }
   
       /**
  -     * 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 @@
       }
   
       /**
  -     * 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 @@
           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;
  
  
  
  1.4       +55 -24    jakarta-ant/src/main/org/apache/tools/ant/filters/LineContainsRegExp.java
  
  Index: LineContainsRegExp.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/filters/LineContainsRegExp.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- LineContainsRegExp.java	15 Apr 2002 13:36:16 -0000	1.3
  +++ LineContainsRegExp.java	30 Apr 2002 10:32:01 -0000	1.4
  @@ -62,60 +62,69 @@
   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:
  - * =======
  - *
  - * &lt;linecontainsregexp&gt;
  + * <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 @@
       }
   
       /**
  -     * 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 @@
       }
   
       /**
  -     * Parse params to add user defined contains strings.
  +     * Parses parameters to add user defined regular expressions.
        */
       private final void initialize() {
           Parameter[] params = getParameters();
  
  
  
  1.4       +55 -30    jakarta-ant/src/main/org/apache/tools/ant/filters/StripLineComments.java
  
  Index: StripLineComments.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/filters/StripLineComments.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- StripLineComments.java	15 Apr 2002 13:36:16 -0000	1.3
  +++ StripLineComments.java	30 Apr 2002 10:32:01 -0000	1.4
  @@ -60,65 +60,71 @@
   import org.apache.tools.ant.types.Parameter;
   
   /**
  - * This is a line comment stripper reader
  + * This filter strips line comments.
    *
    * Example:
  - * =======
    *
  - * &lt;striplinecomments&gt;
  + * <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 @@
       }
   
       /**
  -     * 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 @@
       }
   
       /**
  -     * 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 @@
       }
   
       /**
  -     * 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;
  
  
  
  1.7       +24 -7     jakarta-ant/src/main/org/apache/tools/ant/filters/StringInputStream.java
  
  Index: StringInputStream.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/filters/StringInputStream.java,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- StringInputStream.java	17 Apr 2002 05:50:10 -0000	1.6
  +++ StringInputStream.java	30 Apr 2002 10:32:01 -0000	1.7
  @@ -58,38 +58,53 @@
   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 @@
       }
   
       /**
  -     * Reset the StringReader.
  +     * Resets the StringReader.
  +     * 
  +     * @exception IOException if the StringReader fails to be reset
        */
       public synchronized void reset() throws IOException {
           in.reset();
  
  
  
  1.4       +29 -18    jakarta-ant/src/main/org/apache/tools/ant/filters/ExpandProperties.java
  
  Index: ExpandProperties.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/filters/ExpandProperties.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- ExpandProperties.java	15 Apr 2002 13:36:16 -0000	1.3
  +++ ExpandProperties.java	30 Apr 2002 10:32:01 -0000	1.4
  @@ -59,17 +59,13 @@
   import org.apache.tools.ant.Project;
   
   /**
  - * Expand Ant properties, if any, in the data.
  - *
  - * Example:
  - * =======
  - *
  - * &lt;expandproperties/&gt;
  - *
  + * 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 @@
       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 @@
       }
   
       /**
  -     * 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);
  
  
  
  1.4       +39 -22    jakarta-ant/src/main/org/apache/tools/ant/filters/HeadFilter.java
  
  Index: HeadFilter.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/filters/HeadFilter.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- HeadFilter.java	15 Apr 2002 13:36:16 -0000	1.3
  +++ HeadFilter.java	30 Apr 2002 10:32:01 -0000	1.4
  @@ -59,54 +59,60 @@
   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 @@
       }
   
       /**
  -     * 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 @@
       }
   
       /**
  -     * 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();
  
  
  
  1.4       +40 -21    jakarta-ant/src/main/org/apache/tools/ant/filters/TailFilter.java
  
  Index: TailFilter.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/filters/TailFilter.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- TailFilter.java	15 Apr 2002 13:36:16 -0000	1.3
  +++ TailFilter.java	30 Apr 2002 10:32:01 -0000	1.4
  @@ -59,31 +59,30 @@
   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 @@
       /** 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 @@
       }
   
       /**
  -     * 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 @@
       }
   
       /**
  -     * 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();
  
  
  
  1.5       +17 -8     jakarta-ant/src/main/org/apache/tools/ant/filters/BaseParamFilterReader.java
  
  Index: BaseParamFilterReader.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/filters/BaseParamFilterReader.java,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -r1.4 -r1.5
  --- BaseParamFilterReader.java	15 Apr 2002 13:36:16 -0000	1.4
  +++ BaseParamFilterReader.java	30 Apr 2002 10:32:01 -0000	1.5
  @@ -59,7 +59,7 @@
   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 @@
       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;
       }
  
  
  
  1.8       +3 -2      jakarta-ant/src/main/org/apache/tools/ant/filters/BaseFilterReader.java
  
  Index: BaseFilterReader.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/filters/BaseFilterReader.java,v
  retrieving revision 1.7
  retrieving revision 1.8
  diff -u -r1.7 -r1.8
  --- BaseFilterReader.java	25 Apr 2002 15:14:27 -0000	1.7
  +++ BaseFilterReader.java	30 Apr 2002 10:32:01 -0000	1.8
  @@ -207,13 +207,14 @@
       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;
               }
  
  
  
  1.6       +33 -10    jakarta-ant/src/main/org/apache/tools/ant/filters/StripJavaComments.java
  
  Index: StripJavaComments.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/filters/StripJavaComments.java,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -r1.5 -r1.6
  --- StripJavaComments.java	15 Apr 2002 13:36:16 -0000	1.5
  +++ StripJavaComments.java	30 Apr 2002 10:32:01 -0000	1.6
  @@ -57,8 +57,8 @@
   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 @@
   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 @@
       }
   
       /**
  -     * 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;
  
  
  
  1.4       +74 -37    jakarta-ant/src/main/org/apache/tools/ant/filters/ReplaceTokens.java
  
  Index: ReplaceTokens.java
  ===================================================================
  RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/filters/ReplaceTokens.java,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- ReplaceTokens.java	15 Apr 2002 13:36:16 -0000	1.3
  +++ ReplaceTokens.java	30 Apr 2002 10:32:01 -0000	1.4
  @@ -60,67 +60,73 @@
   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:
    *
  - * &lt;replacetokens begintoken=&quot;#&quot; endtoken=&quot;#&quot;&gt;
  + * <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 @@
       }
   
       /**
  -     * 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 @@
       }
   
       /**
  -     * 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 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;
  
  
  

--
To unsubscribe, e-mail:   <mailto:ant-dev-unsubscribe@jakarta.apache.org>
For additional commands, e-mail: <mailto:ant-dev-help@jakarta.apache.org>


Mime
View raw message