checkstyle - mostly javadoc

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

src/main/org/apache/tools/ant/util/ChainedMapper.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2004 The Apache Software Foundation.
+ * Copyright 2004-2005 The Apache Software Foundation.
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -21,7 +21,6 @@ import java.util.List;
 import java.util.Arrays;
 import java.util.Iterator;
 import java.util.ArrayList;
-import org.apache.tools.ant.types.Mapper;
 
 /**
  * A <CODE>ContainerMapper</CODE> that chains the results of the first

src/main/org/apache/tools/ant/util/CollectionUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2002-2004 The Apache Software Foundation
+ * Copyright  2002-2005 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -29,8 +29,10 @@ import java.util.Vector;
 public class CollectionUtils {
 
     /**
-     * Please use Vector.equals() or List.equals()
-     *
+     * Please use Vector.equals() or List.equals().
+     * @param v1 the first vector.
+     * @param v2 the second vector.
+     * @return true if the vectors are equal.
      * @since Ant 1.5
      * @deprecated
      */
@@ -48,10 +50,12 @@ public class CollectionUtils {
 
     /**
      * Dictionary does not have an equals.
-     * Please use  Map.equals()
+     * Please use  Map.equals().
      *
      * <p>Follows the equals contract of Java 2's Map.</p>
-     *
+     * @param d1 the first directory.
+     * @param d2 the second directory.
+     * @return true if the directories are equal.
      * @since Ant 1.5
      * @deprecated
      */
@@ -86,7 +90,8 @@ public class CollectionUtils {
 
     /**
      * Dictionary does not know the putAll method. Please use Map.putAll().
-     *
+     * @param m1 the to directory.
+     * @param m2 the from directory.
      * @since Ant 1.6
      * @deprecated
      */
@@ -98,16 +103,25 @@ public class CollectionUtils {
     }
 
     /**
+     * An empty enumeration.
      * @since Ant 1.6
      */
     public static final class EmptyEnumeration implements Enumeration {
+        /** Constructor for the EmptyEnumeration */
         public EmptyEnumeration() {
         }
 
+        /**
+         * @return false always.
+         */
         public boolean hasMoreElements() {
             return false;
         }
 
+        /**
+         * @return nothing.
+         * @throws NoSuchElementException always.
+         */
         public Object nextElement() throws NoSuchElementException {
             throw new NoSuchElementException();
         }
@@ -116,9 +130,9 @@ public class CollectionUtils {
     /**
      * Append one enumeration to another.
      * Elements are evaluated lazily.
-     * @param e1 the first enumeration
-     * @param e2 the subsequent enumeration
-     * @return an enumeration representing e1 followed by e2
+     * @param e1 the first enumeration.
+     * @param e2 the subsequent enumeration.
+     * @return an enumeration representing e1 followed by e2.
      * @since Ant 1.6.3
      */
     public static Enumeration append(Enumeration e1, Enumeration e2) {

src/main/org/apache/tools/ant/util/ConcatFileInputStream.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2004 The Apache Software Foundation
+ * Copyright 2004-2005 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -112,13 +112,7 @@ public class ConcatFileInputStream extends InputStream {
     }
 
     private void closeCurrent() {
-        if (currentStream != null) {
-            try {
-                currentStream.close();
-            } catch (IOException eyeOhEx) {
-            }
-            currentStream = null;
-        }
+        FileUtils.close(currentStream);
+        currentStream = null;
     }
 }
-

src/main/org/apache/tools/ant/util/ContainerMapper.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2004 The Apache Software Foundation.
+ * Copyright 2004-2005 The Apache Software Foundation.
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -86,12 +86,14 @@ public abstract class ContainerMapper implements FileNameMapper {
 
     /**
      * Empty implementation.
+     * @param ignore ignored.
      */
     public void setFrom(String ignore) {
     }
 
     /**
      * Empty implementation.
+     * @param ignore ignored.
      */
     public void setTo(String ignore) {
     }

src/main/org/apache/tools/ant/util/DOMElementWriter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2000-2004 The Apache Software Foundation
+ * Copyright  2000-2005 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -145,6 +145,8 @@ public class DOMElementWriter {
                 }
                 out.write("?>");
                 break;
+            default:
+                // Do nothing
             }
         }
 
@@ -168,6 +170,8 @@ public class DOMElementWriter {
     /**
      * Escape <, > & ', " as their entities and
      * drop characters that are illegal in XML documents.
+     * @param value the string to encode.
+     * @return the encoded string.
      */
     public String encode(String value) {
         StringBuffer sb = new StringBuffer();
@@ -217,6 +221,8 @@ public class DOMElementWriter {
      * href="http://www.w3.org/TR/1998/REC-xml-19980210#charsets">http://www.w3.org/TR/1998/REC-xml-19980210#charsets</a> and
      * 2.7 <a
      * href="http://www.w3.org/TR/1998/REC-xml-19980210#sec-cdata-sect">http://www.w3.org/TR/1998/REC-xml-19980210#sec-cdata-sect</a>.</p>
+     * @param value the value to be encoded.
+     * @return the encoded value.
 
      */
     public String encodedata(final String value) {
@@ -244,6 +250,8 @@ public class DOMElementWriter {
 
     /**
      * Is the given argument a character or entity reference?
+     * @param ent the value to be checked.
+     * @return true if it is an entity.
      */
     public boolean isReference(String ent) {
         if (!(ent.charAt(0) == '&') || !ent.endsWith(";")) {
@@ -283,7 +291,8 @@ public class DOMElementWriter {
      * <p>See XML 1.0 2.2 <a
      * href="http://www.w3.org/TR/1998/REC-xml-19980210#charsets">
      * http://www.w3.org/TR/1998/REC-xml-19980210#charsets</a>.</p>
-     *
+     * @param c the character to test.
+     * @return true if the character is allowed.
      * @since 1.10, Ant 1.5
      */
     public boolean isLegalCharacter(char c) {

src/main/org/apache/tools/ant/util/DateUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2002-2004 The Apache Software Foundation
+ * Copyright  2002-2005 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -171,6 +171,8 @@ public final class DateUtils {
      * + 11/22 for rounding
      * </pre>
      *
+     * @param cal the calander.
+     *
      * @return The phase of the moon as a number between 0 and 7 with
      *         0 meaning new moon and 4 meaning full moon.
      *
@@ -189,7 +191,7 @@ public final class DateUtils {
     /**
      * Returns the current Date in a format suitable for a SMTP date
      * header.
-     *
+     * @return the current date.
      * @since Ant 1.5.2
      */
     public static String getDateForHeader() {

src/main/org/apache/tools/ant/util/FileNameMapper.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2000,2004 The Apache Software Foundation
+ * Copyright  2000,2004-2005 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -32,11 +32,13 @@ public interface FileNameMapper {
 
     /**
      * Sets the from part of the transformation rule.
+     * @param from a string.
      */
     void setFrom(String from);
 
     /**
      * Sets the to part of the transformation rule.
+     * @param to a string.
      */
     void setTo(String to);
 
@@ -50,6 +52,8 @@ public interface FileNameMapper {
      *
      * @param sourceFileName the name of the source file relative to
      *                       some given basedirectory.
+     * @return an array of strings if the ruld applies to the source file, or
+     *         null if it does not.
      */
     String[] mapFileName(String sourceFileName);
 }

src/main/org/apache/tools/ant/util/FlatFileNameMapper.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2000,2004 The Apache Software Foundation
+ * Copyright  2000,2004-2005 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -29,12 +29,14 @@ public class FlatFileNameMapper implements FileNameMapper {
 
     /**
      * Ignored.
+     * @param from ignored.
      */
     public void setFrom(String from) {
     }
 
     /**
      * Ignored.
+     * @param to ignored.
      */
     public void setTo(String to) {
     }
@@ -42,6 +44,8 @@ public class FlatFileNameMapper implements FileNameMapper {
     /**
      * Returns an one-element array containing the source file name
      * without any leading directory information.
+     * @param sourceFileName the name to map.
+     * @return the file name in a one-element array.
      */
     public String[] mapFileName(String sourceFileName) {
         return new String[] {new java.io.File(sourceFileName).getName()};

src/main/org/apache/tools/ant/util/GlobPatternMapper.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2000,2002,2004 The Apache Software Foundation
+ * Copyright  2000,2002,2004-2005 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -147,7 +147,6 @@ public class GlobPatternMapper implements FileNameMapper {
                               name.length() - postfixLength);
     }
 
-
     /**
      * modify string based on dir char mapping and case sensitivity
      * @param name the name to convert

src/main/org/apache/tools/ant/util/IdentityMapper.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2000,2004 The Apache Software Foundation
+ * Copyright  2000,2004-2005 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -28,18 +28,22 @@ public class IdentityMapper implements FileNameMapper {
 
     /**
      * Ignored.
+     * @param from ignored.
      */
     public void setFrom(String from) {
     }
 
     /**
      * Ignored.
+     * @param to ignored.
      */
     public void setTo(String to) {
     }
 
     /**
      * Returns an one-element array containing the source file name.
+     * @param sourceFileName the name to map.
+     * @return the source filename in a one-element array.
      */
     public String[] mapFileName(String sourceFileName) {
         return new String[] {sourceFileName};

src/main/org/apache/tools/ant/util/JAXPUtils.java

@@ -71,7 +71,8 @@ public class JAXPUtils {
      * Returns the parser factory to use. Only one parser factory is
      * ever created by this method and is then cached for future use.
      *
-     * @return a SAXParserFactory to use
+     * @return a SAXParserFactory to use.
+     * @throws BuildException on error.
      *
      * @since Ant 1.5
      */
@@ -88,7 +89,8 @@ public class JAXPUtils {
      * Returns the parser factory to use to create namespace aware parsers.
      *
      * @return a SAXParserFactory to use which supports manufacture of
-     * namespace aware parsers
+     * namespace aware parsers.
+     * @throws BuildException on error.
      *
      * @since Ant 1.6
      */
@@ -105,6 +107,8 @@ public class JAXPUtils {
     /**
      * Returns a new  parser factory instance.
      *
+     * @return the parser factory.
+     * @throws BuildException on error.
      * @since Ant 1.5
      */
     public static SAXParserFactory newParserFactory() throws BuildException {
@@ -123,6 +127,7 @@ public class JAXPUtils {
      * factory.
      *
      * @return a SAX 1 Parser.
+     * @throws BuildException on error.
      * @see #getParserFactory
      * @since Ant 1.5
      */
@@ -139,6 +144,7 @@ public class JAXPUtils {
      * factory.
      *
      * @return a SAX 2 XMLReader.
+     * @throws BuildException on error.
      * @see #getParserFactory
      * @since Ant 1.5
      */
@@ -154,6 +160,7 @@ public class JAXPUtils {
      * Returns a newly created SAX 2 XMLReader, which is namespace aware
      *
      * @return a SAX 2 XMLReader.
+     * @throws BuildException on error.
      * @see #getParserFactory
      * @since Ant 1.6
      */
@@ -181,7 +188,8 @@ public class JAXPUtils {
     /**
      * Returns a newly created DocumentBuilder.
      *
-     * @return a DocumentBuilder
+     * @return a DocumentBuilder.
+     * @throws BuildException on error.
      * @since Ant 1.6
      */
     public static DocumentBuilder getDocumentBuilder() throws BuildException {

src/main/org/apache/tools/ant/util/JavaEnvUtils.java

@@ -30,20 +30,20 @@ import org.apache.tools.ant.taskdefs.condition.Os;
  *
  * @since Ant 1.5
  */
-public class JavaEnvUtils {
+public final class JavaEnvUtils {
 
     private JavaEnvUtils() {
     }
 
     /** Are we on a DOS-based system */
-    private static final boolean isDos = Os.isFamily("dos");
+    private static final boolean IS_DOS = Os.isFamily("dos");
     /** Are we on Novell NetWare */
-    private static final boolean isNetware = Os.isName("netware");
+    private static final boolean IS_NETWARE = Os.isName("netware");
     /** Are we on AIX */
-    private static final boolean isAix = Os.isName("aix");
+    private static final boolean IS_AIX = Os.isName("aix");
 
     /** shortcut for System.getProperty("java.home") */
-    private static final String javaHome = System.getProperty("java.home");
+    private static final String JAVA_HOME = System.getProperty("java.home");
 
     /** FileUtils instance for path normalization */
     private static final FileUtils FILE_UTILS = FileUtils.getFileUtils();
@@ -127,8 +127,8 @@ public class JavaEnvUtils {
      * Compares the current Java version to the passed in String -
      * assumes the argument is one of the constants defined in this
      * class.
-     * @return true if the version of Java is the same as the given
-     * version.
+     * @param version the version to check against the current version.
+     * @return true if the version of Java is the same as the given version.
      * @since Ant 1.5
      */
     public static boolean isJavaVersion(String version) {
@@ -159,11 +159,12 @@ public class JavaEnvUtils {
      * <code>JAVA_HOME</code> points to your JDK installation.  JDK
      * &lt; 1.2 has them in the same directory as the JDK
      * executables.</p>
-     *
+     * @param command the java executable to find.
+     * @return the path to the command.
      * @since Ant 1.5
      */
     public static String getJreExecutable(String command) {
-        if (isNetware) {
+        if (IS_NETWARE) {
             // Extrapolating from:
             // "NetWare may have a "java" in that directory, but 99% of
             // the time, you don't want to execute it" -- Jeff Tulley
@@ -173,14 +174,14 @@ public class JavaEnvUtils {
 
         File jExecutable = null;
 
-        if (isAix) {
+        if (IS_AIX) {
             // On IBM's JDK 1.2 the directory layout is different, 1.3 follows
             // Sun's layout.
-            jExecutable = findInDir(javaHome + "/sh", command);
+            jExecutable = findInDir(JAVA_HOME + "/sh", command);
         }
 
         if (jExecutable == null) {
-            jExecutable = findInDir(javaHome + "/bin", command);
+            jExecutable = findInDir(JAVA_HOME + "/bin", command);
         }
 
         if (jExecutable != null) {
@@ -199,11 +200,12 @@ public class JavaEnvUtils {
      *
      * <p>You typically find them in <code>JAVA_HOME/bin</code> if
      * <code>JAVA_HOME</code> points to your JDK installation.</p>
-     *
+     * @param command the java executable to find.
+     * @return the path to the command.
      * @since Ant 1.5
      */
     public static String getJdkExecutable(String command) {
-        if (isNetware) {
+        if (IS_NETWARE) {
             // Extrapolating from:
             // "NetWare may have a "java" in that directory, but 99% of
             // the time, you don't want to execute it" -- Jeff Tulley
@@ -213,14 +215,14 @@ public class JavaEnvUtils {
 
         File jExecutable = null;
 
-        if (isAix) {
+        if (IS_AIX) {
             // On IBM's JDK 1.2 the directory layout is different, 1.3 follows
             // Sun's layout.
-            jExecutable = findInDir(javaHome + "/../sh", command);
+            jExecutable = findInDir(JAVA_HOME + "/../sh", command);
         }
 
         if (jExecutable == null) {
-            jExecutable = findInDir(javaHome + "/../bin", command);
+            jExecutable = findInDir(JAVA_HOME + "/../bin", command);
         }
 
         if (jExecutable != null) {
@@ -241,7 +243,7 @@ public class JavaEnvUtils {
     private static String addExtension(String command) {
         // This is the most common extension case - exe for windows and OS/2,
         // nothing for *nix.
-        return command + (isDos ? ".exe" : "");
+        return command + (IS_DOS ? ".exe" : "");
     }
 
     /**
@@ -263,7 +265,7 @@ public class JavaEnvUtils {
 
     /**
      * demand creation of the package list.
-     * When you add a new package, add a new test below
+     * When you add a new package, add a new test below.
      */
 
     private static void buildJrePackages() {
@@ -307,6 +309,7 @@ public class JavaEnvUtils {
 
     /**
      * Testing helper method; kept here for unification of changes.
+     * @return a list of test classes depending on the java version.
      */
     public static Vector getJrePackageTestCases() {
         Vector tests = new Vector();
@@ -351,7 +354,7 @@ public class JavaEnvUtils {
     /**
      * get a vector of strings of packages built into
      * that platforms runtime jar(s)
-     * @return list of packages
+     * @return list of packages.
      */
     public static Vector getJrePackages() {
         if (jrePackages == null) {
@@ -365,9 +368,9 @@ public class JavaEnvUtils {
      * Writes the command into a temporary DCL script and returns the
      * corresponding File object.
      * It is the job of the caller to delete the file on exit.
-     * @param cmd
-     * @return
-     * @throws IOException
+     * @param cmd the command.
+     * @return the file containing the command.
+     * @throws IOException if there is an error writing to the file.
      */
     public static File createVmsJavaOptionFile(String[] cmd)
             throws IOException {

src/main/org/apache/tools/ant/util/KeepAliveInputStream.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2003-2004 The Apache Software Foundation
+ * Copyright  2003-2005 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -37,13 +37,20 @@ import java.io.InputStream;
  */
 public class KeepAliveInputStream extends FilterInputStream {
 
+    /**
+     * Constructor of KeepAliveInputStream.
+     *
+     * @param in an InputStream value, it should be standard input.
+     */
     public KeepAliveInputStream(InputStream in) {
         super(in);
     }
 
-    /** this method does nothing */
+    /**
+     * This method does nothing.
+     * @throws IOException as we are overridding FilterInputStream.
+     */
     public void close() throws IOException {
-        //
+        // do not close the stream
     }
 }
-

src/main/org/apache/tools/ant/util/KeepAliveOutputStream.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2002,2004 The Apache Software Foundation
+ * Copyright  2002,2004-2005 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -36,13 +36,20 @@ import java.io.OutputStream;
  */
 public class KeepAliveOutputStream extends FilterOutputStream {
 
+    /**
+     * Constructor of KeepAliveOutputStream.
+     *
+     * @param out an OutputStream value, it shoudl be standard output.
+     */
     public KeepAliveOutputStream(OutputStream out) {
         super(out);
     }
 
-    /** this method does nothing */
+    /**
+     * This method does nothing.
+     * @throws IOException as we are overridding FilterOutputStream.
+     */
     public void close() throws IOException {
-        //
+        // do not close the stream
     }
 }
-

src/main/org/apache/tools/ant/util/LeadPipeInputStream.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2004 The Apache Software Foundation
+ * Copyright 2004-2005 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -42,6 +42,7 @@ public class LeadPipeInputStream extends PipedInputStream {
      * Construct a new <CODE>LeadPipeInputStream</CODE> to pull
      * from the specified <CODE>PipedOutputStream</CODE>.
      * @param src   the <CODE>PipedOutputStream</CODE> source.
+     * @throws IOException if unable to construct the stream.
      */
     public LeadPipeInputStream(PipedOutputStream src) throws IOException {
         super(src);

src/main/org/apache/tools/ant/util/MergingMapper.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2000,2004 The Apache Software Foundation
+ * Copyright  2000,2004-2005 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -30,12 +30,14 @@ public class MergingMapper implements FileNameMapper {
 
     /**
      * Ignored.
+     * @param from ignored.
      */
     public void setFrom(String from) {
     }
 
     /**
      * Sets the name of the merged file.
+     * @param to the name of the merged file.
      */
     public void setTo(String to) {
         mergedFile = new String[] {to};
@@ -43,6 +45,8 @@ public class MergingMapper implements FileNameMapper {
 
     /**
      * Returns an one-element array containing the file name set via setTo.
+     * @param sourceFileName ignored.
+     * @return a one-element array containing the merged filename.
      */
     public String[] mapFileName(String sourceFileName) {
         return mergedFile;