Update javadoc task to support multiple link and group options.

Submitted by:	Patrick Chanezon <chanezon@netscape.com>


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

docs/index.html

@@ -13,6 +13,7 @@
 <ul>
   <li>Jacques Bergeron (<a href="mailto:jacques.bergeron@dogico.com">jacques.bergeron@dogico.com</a>)</li>
   <li>Stefan Bodewig (<a href="mailto:stefan.bodewig@megabit.net">stefan.bodewig@megabit.net</a>)</li>
+  <li>Patrick Chanezon (<a href="mailto:chanezon@netscape.com">chanezon@netscape.com</a>)</li>
   <li>James Duncan Davison (<a href="mailto:duncan@x180.com">duncan@x180.com</a>)</li>
   <li>Tom Dimock (<a href="mailto:tad1@cornell.edu">tad1@cornell.edu</a>)</li>
   <li>Bill Kelly (<a href="mailto:bill.kelly@softwired-inc.com">bill.kelly@softwired-inc.com</a>)</li>
@@ -1660,23 +1661,34 @@ The classpath used contains <code>xyz.jar</code>, and debug information is on.
 Only files under <code>mypackage/p1</code> and <code>mypackage/p2</code> are
 used. Files in the <code>mypackage/p1/testpackage</code> directory are excluded
 form compilation and copy.</p>
+
 <hr>
 <h2><a name="javadoc">Javadoc/Javadoc2</a></h2>
 <h3>Description</h3>
 <p>Generates code documentation using the javadoc tool.</p>
-<p>The source directory will be recursively scanned for Java source files to but
-only those matching the inclusion rules will be passed to the javadoc tool. This
+<p>The source directory will be recursively scanned for Java source files to process
+but only those matching the inclusion rules will be passed to the javadoc tool. This
 allows wildcards to be used to choose between package names, reducing verbosity
 and management costs over time. This task, however, has no notion of
-&quot;changed&quot; files, unlike the <a href="#javac">javac</a> task, but it's
-not used so frequently.</p>
+&quot;changed&quot; files, unlike the <a href="#javac">javac</a> task. This means
+all packages will be processed each time this task is run. In general, however,
+this task is used much less frequently.</p>
 <p>This task works seamlessly between different javadoc versions (1.1 and 1.2),
 with the obvious restriction that the 1.2 attributes will be ignored if run in a
 1.1 VM.</p>
-<p>NOTE: since javadoc calls System.exit(), we cannot run javadoc inside the
-same VM without breaking functionality. For this reason, this task always forks
-the VM. But this is not a performance penalty since javadoc is normally a heavy
-application and must be called just once.</p>
+<p>NOTE: since javadoc calls System.exit(), javadoc cannot be run inside the
+same VM as ant without breaking functionality. For this reason, this task 
+always forks the VM. This overhead is not significant since javadoc is normally a heavy
+application and will be called infrequently.</p>
+<p>NOTE: the packagelist attribute allows you to specify the list of packages to 
+document outside of the Ant file. It's a much better practice to include everything 
+inside the build.xml file. This option was added in order to make it easier to 
+migrate from regular makefiles, where you would use this option of javadoc. 
+The packages listed in packagelist are not checked, so the task performs even 
+if some packages are missing or broken. Use this option if you wish to convert from 
+an existing makefile. Once things are running you should then switch to the regular 
+notation. 
+
 <p>DEPRECATION: the javadoc2 task simply points to the javadoc task and it's
 there for back compatibility reasons. Since this task will be removed in future
 versions, you are strongly encouraged to use <a href="#javadoc">javadoc</a>
@@ -1701,6 +1713,12 @@ instead.</p>
     <td align="center" valign="top">all</td>
     <td align="center" valign="top">Yes</td>
   </tr>
+  <tr>
+    <td valign="top">maxmemory</td>
+    <td valign="top">Max amount of memory to allocate to the javadoc VM</td>
+    <td align="center" valign="top">all</td>
+    <td align="center" valign="top">No</td>
+  </tr>
   <tr>
     <td valign="top">sourcefiles</td>
     <td valign="top">Space separated list of source files</td>
@@ -1714,7 +1732,13 @@ instead.</p>
     <td align="center" valign="top">all</td>
   </tr>
   <tr>
-    <td valign="top">Classpath</td>
+    <td valign="top">packageList</td>
+    <td valign="top">The name of a file containing the packages to process</td>
+    <td align="center" valign="top">all</td>
+    <td align="center" valign="top">No</td>
+  </tr>
+  <tr>
+    <td valign="top">classpath</td>
     <td valign="top">Specify where to find user class files</td>
     <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
@@ -1929,14 +1953,81 @@ instead.</p>
   <tr>
     <td valign="top">doclet</td>
     <td valign="top">Specifies the class file that starts the doclet used in generating the documentation.</td>
+    <td align="center" valign="top">1.2</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">docletpath</td>
     <td valign="top">Specifies the path to the doclet class file that is specified with the -doclet option.</td>
+    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">No</td>
+  </tr>
+  <tr>
+    <td valign="top">additionalparam</td>
+    <td valign="top">Lets you add additional parameters to the javadoc command line. Useful for doclets</td>
+    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">No</td>
+  </tr>
+</table>
+
+<h3>Parameters specified as subelements</h3>
+Two parameters of the Javadoc task may be specified as nested elements of the
+Javadoc task element: link and group.
+When present, there can be any number of each of these elements.
+They perform the same role as the link, linkoffline and
+group attributes. You can use either syntax (or both at once), but with the  nested 
+elements you can easily specify multiple occurrences of the arguments.
+<h4>link</h4>
+Create link to javadoc output at the given URL
+<h4>Parameters</h4>
+
+<table width="60%" border="1" cellpadding="2" cellspacing="0">
+  <tr>
+    <td valign="top"><b>Attribute</b></td>
+    <td valign="top"><b>Description</b></td>
+    <td align="center" valign="top"><b>Required</b></td>
+  </tr>
+  <tr>
+    <td valign="top">href</td>
+    <td valign="top">The URL for the external documentation you wish to link to</td>
+    <td align="center" valign="top">Yes</td>
+  </tr>
+  <tr>
+    <td valign="top">offline</td>
+    <td valign="top">True if this link is not available online at the time of 
+                     generating the documentation</td>
     <td align="center" valign="top">No</td>
   </tr>
+  <tr>
+    <td valign="top">packagelistLoc</td>
+    <td valign="top">The location to the directory containing the package-list file for
+                     the external documentation</td>
+    <td align="center" valign="top">Only if the offline attribute is true</td>
+  </tr>
+</table>
+  
+<h4>groups</h4>
+Separates packages on the overview page into whatever groups you specify,
+one group per table.
+
+<table width="60%" border="1" cellpadding="2" cellspacing="0">
+  <tr>
+    <td valign="top"><b>Attribute</b></td>
+    <td valign="top"><b>Description</b></td>
+    <td align="center" valign="top"><b>Required</b></td>
+  </tr>
+  <tr>
+    <td valign="top">title</td>
+    <td valign="top">Title of the group</td>
+    <td align="center" valign="top">Yes</td>
+  </tr>
+  <tr>
+    <td valign="top">packages</td>
+    <td valign="top">List of packages to include in that group</td>
+    <td align="center" valign="top">Yes</td>
+  </tr>
 </table>
+
 <h3>Example</h3>
 <pre>  &lt;javadoc packagenames=&quot;com.dummy.test.*&quot;
            sourcepath=&quot;src&quot;
@@ -1946,8 +2037,13 @@ instead.</p>
            use=&quot;true&quot;
            windowtitle=&quot;Test API&quot;
            doctitle=&quot;&lt;h1&gt;Test&lt;/h1&gt;&quot;
-           bottom=&quot;&lt;i&gt;Copyright &amp;#169; 2000 Dummy Corp. All Rights Reserved.&lt;/i&gt;&quot;
-  /&gt;</pre>
+           bottom=&quot;&lt;i&gt;Copyright &amp;#169; 2000 Dummy Corp. All Rights Reserved.&lt;/i&gt;&quot;&gt;
+    &lt;group title=&quot;Group 1 Packages&quot; packages=&quot;com.dummy.test.a*&quot;/&gt;
+    &lt;group title=&quot;Group 2 Packages&quot; packages=&quot;com.dummy.test.b*&quot;/&gt;
+    &lt;link offline=&quot;true&quot; href=&quot;http://java.sun.com/products/jdk/1.2/docs/api/&quot; packagelistLoc=&quot;C:\tmp&quot;/&gt;
+    &lt;link href=&quot;http://developer.java.sun.com/developer/products/xml/docs/api/&quot;/&gt;
+  &lt/javadoc&gt;</pre>
+  
 <hr>
 <h2><a name="keysubst">KeySubst</a></h2>
 <h3>Description</h3>

src/main/org/apache/tools/ant/BuildListener.java

@@ -74,7 +74,7 @@ public interface BuildListener extends EventListener {
      *  Fired after the last target has finished. This event
      *  will still be thrown if an error occured during the build.
      *
-     *  @see BuildEvent.getException()
+     *  @see BuildEvent#getException()
      */
     public void buildFinished(BuildEvent event);
 
@@ -89,7 +89,7 @@ public interface BuildListener extends EventListener {
      *  Fired when a target has finished. This event will
      *  still be thrown if an error occured during the build.
      *
-     *  @see BuildEvent.getException()
+     *  @see BuildEvent#getException()
      */
     public void targetFinished(BuildEvent event);
 

src/main/org/apache/tools/ant/DirectoryScanner.java

@@ -808,7 +808,6 @@ strLoop:
     /**
      * Adds the array with default exclusions to the current exclusions set.
      *
-     * @see #DEFAULTEXCLUDES
      */
     public void addDefaultExcludes() {
         int excludesLength = excludes == null ? 0 : excludes.length;

src/main/org/apache/tools/ant/PathTokenizer.java

@@ -0,0 +1,124 @@
+/*
+ * The Apache Software License, Version 1.1
+ *
+ * Copyright (c) 1999 The Apache Software Foundation.  All rights
+ * reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in
+ *    the documentation and/or other materials provided with the
+ *    distribution.
+ *
+ * 3. The end-user documentation included with the redistribution, if
+ *    any, must include the following acknowlegement:
+ *       "This product includes software developed by the
+ *        Apache Software Foundation (http://www.apache.org/)."
+ *    Alternately, this acknowlegement may appear in the software itself,
+ *    if and wherever such third-party acknowlegements normally appear.
+ *
+ * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
+ *    Foundation" must not be used to endorse or promote products derived
+ *    from this software without prior written permission. For written
+ *    permission, please contact apache@apache.org.
+ *
+ * 5. Products derived from this software may not be called "Apache"
+ *    nor may "Apache" appear in their names without prior written
+ *    permission of the Apache Group.
+ *
+ * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+ * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
+ * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ * SUCH DAMAGE.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation.  For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ */
+package org.apache.tools.ant;
+
+import java.util.*;
+import java.io.*;
+
+/**
+ * A Path tokenizer takes a path and returns the components that make up
+ * that path.
+ *
+ * The path can use path separators of either ':' or ';' and file separators
+ * of either '/' or '\'
+ *
+ * @author Conor MacNeill (conor@ieee.org)
+ *
+ */ 
+public class PathTokenizer {
+    /**
+     * A tokenizer to break the string up based on the ':' or ';' separators.
+     */
+    StringTokenizer tokenizer;
+    
+    /**
+     * A String which stores any path components which have been read ahead.
+     */
+    String lookahead = null;
+
+    public PathTokenizer(String path) {
+       tokenizer = new StringTokenizer(path, ":;", false);
+    }
+
+    public boolean hasMoreTokens() {
+        if (lookahead != null) {
+            return true;
+        }
+        
+        return tokenizer.hasMoreTokens();
+    }
+    
+    public String nextToken() throws NoSuchElementException {
+        if (lookahead != null) {
+            String token = lookahead;
+            lookahead = null;
+            
+            return token;
+        }
+        else {
+            String token = tokenizer.nextToken().trim();
+            
+            
+            if (token.length() == 1 && Character.isLetter(token.charAt(0))
+                                    && File.pathSeparator.equals(";") 
+                                    && tokenizer.hasMoreTokens()) {
+                // we are on a dos style system so this path could be a drive
+                // spec. We look at the next token
+                String nextToken = tokenizer.nextToken().trim();
+                if (nextToken.startsWith("\\") || nextToken.startsWith("/")) {
+                    // we know we are on a DOS style platform and the next path starts with a
+                    // slash or backslash, so we know this is a drive spec
+                    token += ":" + nextToken;
+                }
+                else {
+                    // store the token just read for next time
+                    lookahead = nextToken;
+                }
+            }
+            
+            return token;
+        }
+    }
+}
+          

src/main/org/apache/tools/ant/XmlLogger.java

@@ -62,7 +62,7 @@ import org.w3c.dom.*;
  *  Generates a "log.xml" file in the current directory with
  *  an XML description of what happened during a build.
  *
- *  @see Project#addBuildListener()
+ *  @see Project#addBuildListener(BuildListener)
  */
 public class XmlLogger implements BuildListener {
 

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

@@ -75,11 +75,14 @@ import java.util.*;
  *
  * @author Jon S. Stevens <a href="mailto:jon@clearink.com">jon@clearink.com</a>
  * @author Stefano Mazzocchi <a href="mailto:stefano@apache.org">stefano@apache.org</a>
+ * @author Patrick Chanezon <a href="mailto:chanezon@netscape.com">chanezon@netscape.com</a>
  */
 
 public class Javadoc extends Exec {
 
+    private String maxmemory = null;
     private String sourcePath = null;
+    private String additionalParam = null;
     private File destDir = null;
     private File overviewFile = null;
     private String sourceFiles = null;
@@ -106,8 +109,8 @@ public class Javadoc extends Exec {
     private String header = null;
     private String footer = null;
     private String bottom = null;
-    private String link = null;
     private String linkoffline = null;
+    private String link = null;
     private String group = null;
     private boolean nodeprecated = false;
     private boolean nodeprecatedlist = false;
@@ -119,7 +122,18 @@ public class Javadoc extends Exec {
     private File helpfile = null;
     private String docencoding = null;
     private Vector compileList = new Vector(10);
+    private String packageList = null;
+    private Vector links = new Vector(2);
+    private Vector groups = new Vector(2);
+
+    public void setMaxmemory(String src){
+        maxmemory = src;
+    }
 
+    public void setadditionalParam(String src){
+        additionalParam = src;
+    }
+    
     public void setSourcepath(String src) {
         sourcePath = project.translatePath(src);
     }
@@ -201,15 +215,15 @@ public class Javadoc extends Exec {
     public void setBottom(String src) {
         bottom = src;
     }
-    public void setLink(String src) {
-        link = src;
-    }
     public void setLinkoffline(String src) {
         linkoffline = src;
     }
     public void setGroup(String src) {
         group = src;
     }
+    public void setLink(String src) {
+        link = src;
+    }
     public void setNodeprecated(String src) {
         nodeprecated = Project.toBoolean(src);
     }
@@ -234,6 +248,78 @@ public class Javadoc extends Exec {
     public void setDocencoding(String src) {
         docencoding = src;
     }
+    public void setPackageList(String src) {
+        packageList = src;
+    }
+    
+    public LinkArgument createLink() {
+        LinkArgument la = new LinkArgument();
+        links.addElement(la);
+        return la;
+    }
+    
+    public class LinkArgument {
+        private String href;
+        private boolean offline = false;
+        private String packagelistLoc;
+        
+        public LinkArgument() {
+        }
+
+        public void setHref(String hr) {
+            href = hr;
+        }
+        
+        public String getHref() {
+            return href;
+        }
+        
+        public void setPackagelistLoc(String src) {
+            packagelistLoc = src;
+        }
+        
+        public String getPackagelistLoc() {
+            return packagelistLoc;
+        }
+        
+        public void setOffline(String offline) {
+            this.offline = Project.toBoolean(offline);
+        }
+        
+        public boolean isLinkOffline() {
+            return offline;
+        }
+    }
+    
+    public GroupArgument createGroup() {
+        GroupArgument ga = new GroupArgument();
+        groups.addElement(ga);
+        return ga;
+    }
+
+    public class GroupArgument {
+        private String title;
+        private String packages;
+
+        public GroupArgument() {
+        }
+
+        public void setTitle(String src) {
+            title = src;
+        }
+
+        public String getTitle() {
+            return title;
+        }
+
+        public void setPackages(String src) {
+            packages = src;
+        }
+
+        public String getPackages() {
+            return packages;
+        }
+    }
 
     public void execute() throws BuildException {
         if (sourcePath == null && destDir == null ) {
@@ -251,6 +337,16 @@ public class Javadoc extends Exec {
         if (classpath == null)
             classpath = System.getProperty("java.class.path");
 
+
+        if(maxmemory != null){
+            if(javadoc1){
+                argList.addElement("-J-mx" + maxmemory);
+            }
+            else{
+                argList.addElement("-J-Xmx" + maxmemory);
+            }
+        }
+
         if ( (!javadoc1) || (sourcePath == null) ) {
             argList.addElement("-classpath");
             argList.addElement(classpath);
@@ -358,15 +454,46 @@ public class Javadoc extends Exec {
                 argList.addElement("-bottom");
                 argList.addElement(bottom);
             }
+            
+            // add the single link arguments
             if (link != null) {
                 argList.addElement("-link");
                 argList.addElement(link);
             }
+            
+            // add the links arguments
+            if (links.size() != 0) {
+                for (Enumeration e = links.elements(); e.hasMoreElements(); ) {
+                    LinkArgument la = (LinkArgument)e.nextElement();
+                
+                    if (la.getHref() == null) {
+                        throw new BuildException("Links must provide the RUL to the external class documentation.");
+                    }
+                
+                    if (la.isLinkOffline()) {
+                        String packageListLocation = la.getPackagelistLoc();
+                        if (packageListLocation == null) {
+                            throw new BuildException("The package list location for link " + la.getHref() +
+                                                     " must be provided because the link is offline");
+                        }
+                        argList.addElement("-linkoffline");
+                        argList.addElement(la.getHref());
+                        argList.addElement(packageListLocation);
+                    }
+                    else {
+                        argList.addElement("-link");
+                        argList.addElement(la.getHref());
+                    }
+                }
+            }                                   
+                                                
+            // add the single linkoffline arguments
             if (linkoffline != null) {
                 argList.addElement("-linkoffline");
                 argList.addElement(linkoffline);
             }
-
+            
+            // add the single group arguments
             // Javadoc 1.2 rules:
             //   Multiple -group args allowed.
             //   Each arg includes 3 strings: -group [name] [packagelist].
@@ -391,6 +518,27 @@ public class Javadoc extends Exec {
                   }
                 }
             }
+            
+            // add the group arguments
+            if (groups.size() != 0) {
+                String title = null;
+                String packages = null;
+                GroupArgument ga = null;
+                for (int i = 0; i < groups.size(); i++) {
+                    ga = (GroupArgument)groups.get(i);
+                    if (ga != null) {
+                        title = ga.getTitle();
+                        packages = ga.getPackages();
+                    }
+                    if (title != null) {
+                        argList.addElement("-group");
+                        argList.addElement(title);
+                        if (packages != null) {
+                            argList.addElement(packages);
+                        }
+                    }
+                }
+            }
 
             if (stylesheetfile != null) {
                 argList.addElement("-stylesheetfile");
@@ -400,6 +548,9 @@ public class Javadoc extends Exec {
                 argList.addElement("-helpfile");
                 argList.addElement(helpfile.getAbsolutePath());
             }
+            if (additionalParam != null) {
+                argList.addElement(additionalParam);
+            }
         }
 
         if ((packageNames != null) && (packageNames.length() > 0)) {
@@ -425,6 +576,9 @@ public class Javadoc extends Exec {
             }
         }
 
+         if (packageList != null) {
+            argList.addElement("@" + packageList);
+        }
         project.log("Javadoc args: " + argList.toString(), "javadoc", project.MSG_VERBOSE);
 
         project.log("Javadoc execution", project.MSG_INFO);
@@ -453,20 +607,29 @@ public class Javadoc extends Exec {
      * with the packages found in that path subdirs matching one of the given
      * patterns.
      */
-    private void evaluatePackages(String source, Vector packages, Vector argList) {
+    private void evaluatePackages(String sourcePath, Vector packages, Vector argList) {
         project.log("Parsing source files for packages", project.MSG_INFO);
-        project.log("Source dir = " + source, project.MSG_VERBOSE);
+        project.log("Source path = " + sourcePath, project.MSG_VERBOSE);
         project.log("Packages = " + packages, project.MSG_VERBOSE);
 
-        Hashtable map = mapClasses(new File(source));
-
-        Enumeration e = map.keys();
-        while (e.hasMoreElements()) {
-            String pack = (String) e.nextElement();
-            for (int i = 0; i < packages.size(); i++) {
-                if (matches(pack, (String) packages.elementAt(i))) {
-                    argList.addElement(pack);
-                    break;
+        Vector addedPackages = new Vector();
+        PathTokenizer tokenizer = new PathTokenizer(sourcePath);
+        while (tokenizer.hasMoreTokens()) {
+            File source = new File(project.translatePath(tokenizer.nextToken()));
+            
+            Hashtable map = mapClasses(source);
+
+            Enumeration e = map.keys();
+            while (e.hasMoreElements()) {
+                String pack = (String) e.nextElement();
+                for (int i = 0; i < packages.size(); i++) {
+                    if (matches(pack, (String) packages.elementAt(i))) {
+                        if (!addedPackages.contains(pack)) {
+                            argList.addElement(pack);
+                            addedPackages.addElement(pack);
+                        }
+                        break;
+                    }
                 }
             }
         }

src/main/org/apache/tools/ant/taskdefs/optional/RenameExtensions.java

@@ -73,7 +73,6 @@ import org.apache.tools.ant.taskdefs.*;
 /**
  *
  * @author  dion
- * @version
  */
 public class RenameExtensions extends MatchingTask {