javadoc

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

src/main/org/apache/tools/ant/taskdefs/Jar.java

@@ -151,6 +151,8 @@ public class Jar extends Zip {
     }
 
     /**
+     * Not used for jar files.
+     * @param we not used
      * @ant.attribute ignore="true"
      */
     public void setWhenempty(WhenEmpty we) {
@@ -159,6 +161,8 @@ public class Jar extends Zip {
     }
 
     /**
+     * Set the destination file.
+     * @param jarFile the destination file
      * @deprecated Use setDestFile(File) instead
      */
     public void setJarfile(File jarFile) {
@@ -168,14 +172,16 @@ public class Jar extends Zip {
     /**
      * Set whether or not to create an index list for classes.
      * This may speed up classloading in some cases.
+     * @param flag a <code>boolean</code> value
      */
     public void setIndex(boolean flag) {
         index = flag;
     }
 
     /**
-     * Set whether or not to create an index list for classes.
-     * This may speed up classloading in some cases.
+     * The character encoding to use in the manifest file.
+     *
+     * @param manifestEncoding the character encoding
      */
     public void setManifestEncoding(String manifestEncoding) {
         this.manifestEncoding = manifestEncoding;
@@ -185,8 +191,8 @@ public class Jar extends Zip {
      * Allows the manifest for the archive file to be provided inline
      * in the build file rather than in an external file.
      *
-     * @param newManifest
-     * @throws ManifestException
+     * @param newManifest an embedded manifest element
+     * @throws ManifestException on error
      */
     public void addConfiguredManifest(Manifest newManifest)
         throws ManifestException {
@@ -331,6 +337,8 @@ public class Jar extends Zip {
     }
 
     /**
+     * Add a path to index jars.
+     * @param p a path
      * @since Ant 1.6.2
      */
     public void addConfiguredIndexJars(Path p) {
@@ -340,6 +348,12 @@ public class Jar extends Zip {
         indexJars.append(p);
     }
 
+    /**
+     * Initialize the zip output stream.
+     * @param zOut the zip output stream
+     * @throws IOException on I/O errors
+     * @throws BuildException on other errors
+     */
     protected void initZipOutputStream(ZipOutputStream zOut)
         throws IOException, BuildException {
 
@@ -410,6 +424,13 @@ public class Jar extends Zip {
         super.initZipOutputStream(zOut);
     }
 
+    /**
+     * Finalize the zip output stream.
+     * This creates an index list if the index attribute is true.
+     * @param zOut the zip output stream
+     * @throws IOException on I/O errors
+     * @throws BuildException on other errors
+     */
     protected void finalizeZipOutputStream(ZipOutputStream zOut)
         throws IOException, BuildException {
 
@@ -484,6 +505,14 @@ public class Jar extends Zip {
 
     /**
      * Overridden from Zip class to deal with manifests and index lists.
+     * @param is the input stream
+     * @param zOut the zip output stream
+     * @param vPath the name this entry shall have in the archive
+     * @param lastModified last modification time for the entry.
+     * @param fromArchive the original archive we are copying this
+     *                    entry from, will be null if we are not copying from an archive.
+     * @param mode the Unix permissions to set.
+     * @throws IOException on error
      */
     protected void zipFile(InputStream is, ZipOutputStream zOut, String vPath,
                            long lastModified, File fromArchive, int mode)
@@ -637,6 +666,12 @@ public class Jar extends Zip {
         return super.getResourcesToAdd(filesets, zipFile, needsUpdate);
     }
 
+    /**
+     * Create an empty jar file.
+     * @param zipFile the file to create
+     * @return true for historic reasons
+     * @throws BuildException on error
+     */
     protected boolean createEmptyZip(File zipFile) throws BuildException {
         if (!createEmpty) {
             return true;
@@ -667,6 +702,7 @@ public class Jar extends Zip {
                     zOut.close();
                 }
             } catch (IOException ex) {
+                // Ignore close exception
             }
             createEmpty = false;
         }
@@ -708,7 +744,14 @@ public class Jar extends Zip {
         index = false;
     }
 
+    /**
+     * The manifest config enumerated type.
+     */
     public static class FilesetManifestConfig extends EnumeratedAttribute {
+        /**
+         * Get the list of valid strings.
+         * @return the list of values - "skip", "merge" and "mergewithoutmain"
+         */
         public String[] getValues() {
             return new String[] {"skip", "merge", "mergewithoutmain"};
         }
@@ -718,6 +761,10 @@ public class Jar extends Zip {
      * Writes the directory entries from the first and the filenames
      * from the second list to the given writer, one entry per line.
      *
+     * @param dirs a list of directories
+     * @param files a list of files
+     * @param writer the writer to write to
+     * @throws IOException on error
      * @since Ant 1.6.2
      */
     protected final void writeIndexLikeList(List dirs, List files,
@@ -776,6 +823,9 @@ public class Jar extends Zip {
      * <p>if there is a classpath and the given file doesn't match any
      * of its entries, return null.</p>
      *
+     * @param fileName the name to look for
+     * @param classpath the classpath to look in (may be null)
+     * @return the matching entry, or null if the file is not found
      * @since Ant 1.6.2
      */
     protected static final String findJarName(String fileName,
@@ -819,8 +869,11 @@ public class Jar extends Zip {
     /**
      * Grab lists of all root-level files and all directories
      * contained in the given archive.
-     *
+     * @param file the zip file to examine
+     * @param dirs where to place the directories found
+     * @param files where to place the files found
      * @since Ant 1.7
+     * @throws IOException on error
      */
     protected static final void grabFilesAndDirs(String file, List dirs,
                                                  List files)

src/main/org/apache/tools/ant/taskdefs/Javadoc.java

@@ -486,6 +486,7 @@ public class Javadoc extends Task {
 
     /**
      * Adds a command-line argument.
+     * @return a command-line argument to configure
      * @since Ant 1.6
      */
     public Commandline.Argument createArg() {
@@ -1064,6 +1065,7 @@ public class Javadoc extends Task {
 
     /**
      * Create links to javadoc output at the given URL.
+     * @param src the URL to link to
      */
     public void setLink(String src) {
         if (!javadoc1) {
@@ -1199,30 +1201,55 @@ public class Javadoc extends Task {
         private boolean offline = false;
         private File packagelistLoc;
 
+        /** Constructor for LinkArguement */
         public LinkArgument() {
             //empty
         }
 
+        /**
+         * Set the href attribute.
+         * @param hr a <code>String</code> value
+         */
         public void setHref(String hr) {
             href = hr;
         }
 
+        /**
+         * Get the href attribute.
+         * @return the href attribute.
+         */
         public String getHref() {
             return href;
         }
 
+        /**
+         * Set the packetlist location attribute.
+         * @param src a <code>File</code> value
+         */
         public void setPackagelistLoc(File src) {
             packagelistLoc = src;
         }
 
+        /**
+         * Get the packetList location attribute.
+         * @return the packetList location attribute.
+         */
         public File getPackagelistLoc() {
             return packagelistLoc;
         }
 
+        /**
+         * Set the offline attribute.
+         * @param offline a <code>boolean</code> value
+         */
         public void setOffline(boolean offline) {
             this.offline = offline;
         }
 
+        /**
+         * Get the linkOffline attribute.
+         * @return the linkOffline attribute.
+         */
         public boolean isLinkOffline() {
             return offline;
         }
@@ -1233,6 +1260,7 @@ public class Javadoc extends Task {
      * custom tags. This argument is only available for JavaDoc 1.4,
      * and will generate a verbose message (and then be ignored)
      * when run on Java versions below 1.4.
+     * @return tag argument to be configured
      */
     public TagArgument createTag() {
         if (!javadoc4) {
@@ -1372,11 +1400,11 @@ public class Javadoc extends Task {
 
         /**
          * Returns the -tag parameter this argument represented.
-         *
+         * @return the -tag parameter as a string
          * @exception BuildException if either the name or description
          *                           is <code>null</code> or empty.
          */
-        public String getParameter () throws BuildException {
+        public String getParameter() throws BuildException {
             if (name == null || name.equals("")) {
                 throw new BuildException ("No name specified for custom tag.");
             }
@@ -1392,6 +1420,7 @@ public class Javadoc extends Task {
     /**
      * Separates packages on the overview page into whatever
      * groups you specify, one group per table.
+     * @return a group argument to be configured
      */
     public GroupArgument createGroup() {
         GroupArgument ga = new GroupArgument();
@@ -1399,27 +1428,48 @@ public class Javadoc extends Task {
         return ga;
     }
 
+
+    /**
+     * A class corresponding to the group nested element.
+     */
     public class GroupArgument {
         private Html title;
         private Vector packages = new Vector();
 
+        /** Constructor for GroupArgument */
         public GroupArgument() {
             //empty
         }
 
+        /**
+         * Set the title attribute using a string.
+         * @param src a <code>String</code> value
+         */
         public void setTitle(String src) {
             Html h = new Html();
             h.addText(src);
             addTitle(h);
         }
+        /**
+         * Set the title attribute using a nested Html value.
+         * @param text a <code>Html</code> value
+         */
         public void addTitle(Html text) {
             title = text;
         }
 
+        /**
+         * Get the title.
+         * @return the title
+         */
         public String getTitle() {
             return title != null ? title.getText() : null;
         }
 
+        /**
+         * Set the packages to javadoc on.
+         * @param src a comma separated list of packages
+         */
         public void setPackages(String src) {
             StringTokenizer tok = new StringTokenizer(src, ",");
             while (tok.hasMoreTokens()) {
@@ -1429,10 +1479,18 @@ public class Javadoc extends Task {
                 addPackage(pn);
             }
         }
+        /**
+         * Add a package nested element.
+         * @param pn a nested element specifing the package.
+         */
         public void addPackage(PackageName pn) {
             packages.addElement(pn);
         }
 
+        /**
+         * Get the packages as a collon separated list.
+         * @return the packages as a string
+         */
         public String getPackages() {
             StringBuffer p = new StringBuffer();
             for (int i = 0; i < packages.size(); i++) {
@@ -1447,6 +1505,7 @@ public class Javadoc extends Task {
 
     /**
      * Charset for cross-platform viewing of generated documentation.
+     * @param src the name of the charset
      */
     public void setCharset(String src) {
         this.add12ArgIfNotEmpty("-charset", src);
@@ -1457,6 +1516,7 @@ public class Javadoc extends Task {
      * a non zero return code)?
      *
      * <p>Default is false.</p>
+     * @param b a <code>boolean</code> value
      */
     public void setFailonerror(boolean b) {
         failOnError = b;
@@ -1465,7 +1525,7 @@ public class Javadoc extends Task {
     /**
      * Enables the -source switch, will be ignored if javadoc is not
      * the 1.4 version.
-     *
+     * @param source a <code>String</code> value
      * @since Ant 1.5
      */
     public void setSource(String source) {
@@ -1481,7 +1541,7 @@ public class Javadoc extends Task {
      *
      * <p>All included directories will be translated into package
      * names be converting the directory separator into dots.</p>
-     *
+     * @param packageSet a directory set
      * @since 1.5
      */
     public void addPackageset(DirSet packageSet) {
@@ -1495,7 +1555,7 @@ public class Javadoc extends Task {
      * will automatically add
      * <code>includes=&quot;**&#47;*.java&quot;</code> to the
      * fileset.</p>
-     *
+     * @param fs a file set
      * @since 1.5
      */
     public void addFileset(FileSet fs) {
@@ -1505,7 +1565,7 @@ public class Javadoc extends Task {
     /**
      * Enables the -linksource switch, will be ignored if javadoc is not
      * the 1.4 version. Default is false
-     *
+     * @param b a <code>String</code> value
      * @since Ant 1.6
      */
     public void setLinksource(boolean b) {
@@ -1519,7 +1579,7 @@ public class Javadoc extends Task {
     /**
      * Enables the -linksource switch, will be ignored if javadoc is not
      * the 1.4 version. Default is false
-     *
+     * @param b a <code>String</code> value
      * @since Ant 1.6
      */
     public void setBreakiterator(boolean b) {
@@ -1533,7 +1593,7 @@ public class Javadoc extends Task {
     /**
      * Enables the -noqualifier switch, will be ignored if javadoc is not
      * the 1.4 version.
-     *
+     * @param noqualifier the parameter to the -noqualifier switch
      * @since Ant 1.6
      */
     public void setNoqualifier(String noqualifier) {
@@ -1544,6 +1604,10 @@ public class Javadoc extends Task {
         this.noqualifier = noqualifier;
     }
 
+    /**
+     * Execute the task.
+     * @throws BuildException on error
+     */
     public void execute() throws BuildException {
         if ("javadoc2".equals(getTaskType())) {
             log("!! javadoc2 is deprecated. Use javadoc instead. !!");
@@ -2122,6 +2186,8 @@ public class Javadoc extends Task {
 
     /**
      * Convenience method to expand properties.
+     * @param content the string to expand
+     * @return the converted string
      */
     protected String expand(String content) {
         return getProject().replaceProperties(content);

src/main/org/apache/tools/ant/taskdefs/Jikes.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2000,2002-2004 The Apache Software Foundation
+ * Copyright  2000,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.
@@ -42,8 +42,9 @@ public class Jikes {
 
     /**
      * Constructs a new Jikes object.
-     * @param jop - Parser to send jike's output to
-     * @param command - name of jikes executable
+     * @param jop      Parser to send jike's output to
+     * @param command  name of jikes executable
+     * @param project  the current project
      */
     protected Jikes(JikesOutputParser jop, String command, Project project) {
         super();

src/main/org/apache/tools/ant/taskdefs/JikesOutputParser.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2000,2002-2004 The Apache Software Foundation
+ * Copyright  2000,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.
@@ -47,18 +47,22 @@ public class JikesOutputParser implements ExecuteStreamHandler {
 
     /**
      * Ignore.
+     * @param os ignored
      */
     public void setProcessInputStream(OutputStream os) {
     }
 
     /**
      * Ignore.
+     * @param is ignored
      */
     public void setProcessErrorStream(InputStream is) {
     }
 
     /**
      * Set the inputstream
+     * @param is the input stream
+     * @throws IOException on error
      */
     public void setProcessOutputStream(InputStream is) throws IOException {
         br = new BufferedReader(new InputStreamReader(is));
@@ -66,6 +70,7 @@ public class JikesOutputParser implements ExecuteStreamHandler {
 
     /**
      * Invokes parseOutput.
+     * @throws IOException on error
      */
     public void start() throws IOException {
         parseOutput(br);
@@ -79,7 +84,8 @@ public class JikesOutputParser implements ExecuteStreamHandler {
 
     /**
      * Construct a new Parser object
-     * @param task - task in which context we are called
+     * @param task      task in which context we are called
+     * @param emacsMode if true output in emacs mode
      */
     protected JikesOutputParser(Task task, boolean emacsMode) {
         super();
@@ -97,6 +103,7 @@ public class JikesOutputParser implements ExecuteStreamHandler {
     /**
      * Parse the output of a jikes compiler
      * @param reader - Reader used to read jikes's output
+     * @throws IOException on error
      */
     protected void parseOutput(BufferedReader reader) throws IOException {
        if (emacsMode) {

src/main/org/apache/tools/ant/taskdefs/KeySubst.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2000,2002-2004 The Apache Software Foundation
+ * Copyright  2000,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.
@@ -45,8 +45,9 @@ public class KeySubst extends Task {
     private Hashtable replacements = new Hashtable();
 
     /**
-        Do the execution.
-    */
+     * Do the execution.
+     * @throws BuildException on error
+     */
     public void execute() throws BuildException {
         log("!! KeySubst is deprecated. Use Filter + Copy instead. !!");
         log("Performing Substitutions");
@@ -96,38 +97,42 @@ public class KeySubst extends Task {
     }
 
     /**
-        Set the source file.
-    */
+     * Set the source file.
+     * @param s the source file
+     */
     public void setSrc(File s) {
         this.source = s;
     }
 
     /**
-        Set the destination file.
-    */
+     * Set the destination file.
+     * @param dest the destination file
+     */
     public void setDest(File dest) {
         this.dest = dest;
     }
 
     /**
-        Sets the separator between name=value arguments
-        in setKeys(). By default it is "*".
-    */
+     * Sets the separator between name=value arguments
+     * in setKeys(). By default it is "*".
+     * @param sep the separator string
+     */
     public void setSep(String sep) {
         this.sep = sep;
     }
     /**
      * Sets the keys.
      *
-        Format string is like this:
-        <p>
-        name=value*name2=value
-        <p>
-        Names are case sensitive.
-        <p>
-        Use the setSep() method to change the * to something else
-        if you need to use * as a name or value.
-    */
+     * Format string is like this:
+     *   <p>
+     *   name=value*name2=value
+     *   <p>
+     *   Names are case sensitive.
+     *   <p>
+     *   Use the setSep() method to change the * to something else
+     *   if you need to use * as a name or value.
+     * @param keys a <code>String</code> value
+     */
     public void setKeys(String keys) {
         if (keys != null && keys.length() > 0) {
             StringTokenizer tok =
@@ -145,6 +150,10 @@ public class KeySubst extends Task {
     }
 
 
+    /**
+     * A test method.
+     * @param args not used
+     */
     public static void main(String[] args) {
         try {
             Hashtable hash = new Hashtable();
@@ -158,10 +167,12 @@ public class KeySubst extends Task {
     }
 
     /**
-        Does replacement on text using the hashtable of keys.
-
-        @return the string with the replacements in it.
-    */
+     * Does replacement on text using the hashtable of keys.
+     * @param origString an input string
+     * @param keys       mapping of keys to values
+     * @return the string with the replacements in it.
+     * @throws BuildException on error
+     */
     public static String replace(String origString, Hashtable keys)
         throws BuildException {
         StringBuffer finalString = new StringBuffer();