Add some nested elements to javadoc where it seemed to be useful.

Submitted by:	Jesse Glick <Jesse.Glick@netbeans.com>


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

build.xml

@@ -556,11 +556,12 @@
              author="true"
              version="true"
              windowtitle="${Name} API"
-             doctitle="${Name}"
-             bottom="Copyright © 2000 Apache Software Foundation. All Rights Reserved.">
+             doctitle="${Name}">
       <group title="Ant Core" packages="org.apache.tools.ant*" />
       <group title="Core Tasks" packages="org.apache.tools.ant.taskdefs*" />
       <group title="Optional Tasks" packages="org.apache.tools.ant.taskdefs.optional*" />
+
+      <bottom>Copyright &#169; 1999-2001 Apache Software Foundation. All Rights Reserved.</bottom>
     </javadoc>
   </target>
   

docs/manual/CoreTasks/javadoc.html

@@ -75,7 +75,8 @@ instead.</i></p>
     <td valign="top">sourcefiles</td>
     <td valign="top">Comma separated list of source files</td>
     <td align="center" valign="top">all</td>
-    <td align="center" valign="middle" rowspan="2">at least one of the two</td>
+    <td align="center" valign="middle" rowspan="2">at least one of the two
+    or nested <code>&lt;source&gt;</code> or <code>&lt;package&gt;</code></td>
   </tr>
   <tr>
     <td valign="top">packagenames</td>
@@ -129,6 +130,13 @@ instead.</i></p>
     <td align="center" valign="top">1.2</td>
     <td align="center" valign="top">No</td>
   </tr>
+  <tr>
+    <td valign="top">access</td>
+    <td valign="top">Access mode: one of <code>public</code>, <code>protected</code>,
+                     <code>package</code>, or <code>private</code></td>
+    <td align="center" valign="top">all</td>
+    <td align="center" valign="top">No (default <code>protected</code>)</td>
+  </tr>
   <tr>
     <td valign="top">Public</td>
     <td valign="top">Show only public classes and members</td>
@@ -382,13 +390,71 @@ recommended.</p>
 </pre></p>
 
 <h3>Parameters specified as nested elements</h3>
+
+<h4>package</h4>
+<p>Same as one entry in the list given by <code>packagenames</code>.</p>
+
+<h5>Parameters</h5>
+<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">name</td>
+    <td valign="top">The package name (may be a wildcard)</td>
+    <td align="center" valign="top">Yes</td>
+  </tr>
+</table>
+  
+<h4>excludepackage</h4>
+<p>Same as one entry in the list given by <code>excludepackagenames</code>.</p>
+
+<h5>Parameters</h5>
+Same as for <code>package</code>.
+
+<h4>source</h4>
+<p>Same as one entry in the list given by <code>sourcefiles</code>.</p>
+
+<h5>Parameters</h5>
+<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">file</td>
+    <td valign="top">The source file to document</td>
+    <td align="center" valign="top">Yes</td>
+  </tr>
+</table>
+
+<h4>doctitle</h4>
+
+<p>Same as the <code>doctitle</code> attribute, but you can nest text
+inside the element this way.</p>
+
+<h4>header</h4>
+
+<p>Similar to <code>&lt;doctitle&gt;</code>.</p>
+
+<h4>footer</h4>
+
+<p>Similar to <code>&lt;doctitle&gt;</code>.</p>
+
+<h4>bottom</h4>
+
+<p>Similar to <code>&lt;doctitle&gt;</code>.</p>
+
 <h4>link</h4>
 <p>Create link to javadoc output at the given URL. This performs the
 same role as the link and linkoffline attributes. You can use either
 syntax (or both at once), but with the nested elements you can easily
 specify multiple occurrences of the arguments.</p>
-<h4>Parameters</h4>
 
+<h5>Parameters</h5>
 <table width="60%" border="1" cellpadding="2" cellspacing="0">
   <tr>
     <td valign="top"><b>Attribute</b></td>
@@ -421,6 +487,7 @@ attribute. You can use either syntax (or both at once), but with the
 nested elements you can easily specify multiple occurrences of the
 arguments.</p>
 
+<h5>Parameters</h5>
 <table width="60%" border="1" cellpadding="2" cellspacing="0">
   <tr>
     <td valign="top"><b>Attribute</b></td>
@@ -430,15 +497,19 @@ arguments.</p>
   <tr>
     <td valign="top">title</td>
     <td valign="top">Title of the group</td>
-    <td align="center" valign="top">Yes</td>
+    <td align="center" valign="top">Yes, unless nested <code>&lt;title&gt;</code> given</td>
   </tr>
   <tr>
     <td valign="top">packages</td>
     <td valign="top">List of packages to include in that group. Multiple packages are separated with ':'.</td>
-    <td align="center" valign="top">Yes</td>
+    <td align="center" valign="top">Yes, unless nested <code>&lt;package&gt;</code>s given</td>
   </tr>
 </table>
 
+<p>The title may be specified as a nested <code>&lt;title&gt;</code> element
+with text contents, and the packages may be listed with nested
+<code>&lt;package&gt;</code> elements as for the main task.
+
 <h4>doclet</h4>
 <p>The doclet nested element is used to specify the doclet that javadoc will 
 use to process the input source files. A number of the standard javadoc arguments
@@ -477,9 +548,9 @@ respectively.</p>
            author=&quot;true&quot;
            version=&quot;true&quot;
            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;
+           windowtitle=&quot;Test API&quot;&gt;
+    &lt;doctitle&gt;&lt;![CDATA[&lt;h1&gt;Test&lt;/h1&gt;]]&gt;&lt;/doctitle&gt;
+    &lt;bottom&gt;&lt;![CDATA[&lt;i&gt;Copyright &amp;#169; 2000 Dummy Corp. All Rights Reserved.&lt;/i&gt;]]&gt;&lt;/bottom&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*:com.dummy.test.c*&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;

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

@@ -164,6 +164,44 @@ public class Javadoc extends Task {
         }
     }
 
+    public static class PackageName {
+        private String name;
+        public void setName(String name) {
+            this.name = name;
+        }
+        public String getName() {
+            return name;
+        }
+    }
+
+    public static class SourceFile {
+        private File file;
+        public void setFile(File file) {
+            this.file = file;
+        }
+        public File getFile() {
+            return file;
+        }
+    }
+
+    public static class Html {
+        private StringBuffer text = new StringBuffer();
+        public void addText(String t) {
+            text.append(t);
+        }
+        public String getText() {
+            return text.toString();
+        }
+    }
+
+    public static class AccessType extends EnumeratedAttribute {
+        public String[] getValues() {
+            // Protected first so if any GUI tool offers a default
+            // based on enum #0, it will be right.
+            return new String[] {"protected", "public", "package", "private"};
+        }
+    }
+
     private Commandline cmd = new Commandline();
     private static boolean javadoc1 = 
         (Project.getJavaVersion() == Project.JAVA_1_1);
@@ -204,9 +242,9 @@ public class Javadoc extends Task {
     private boolean failOnError = false;
     private Path sourcePath = null;
     private File destDir = null;
-    private String sourceFiles = null;
-    private String packageNames = null;
-    private String excludePackageNames = null;
+    private Vector sourceFiles = new Vector();
+    private Vector packageNames = new Vector(5);
+    private Vector excludePackageNames = new Vector(1);
     private boolean author = true;
     private boolean version = true;
     private DocletInfo doclet = null;
@@ -218,6 +256,10 @@ public class Javadoc extends Task {
     private Vector links = new Vector(2);
     private Vector groups = new Vector(2);
     private boolean useDefaultExcludes = true;
+    private Html doctitle = null;
+    private Html header = null;
+    private Html footer = null;
+    private Html bottom = null;
 
     /**
      * Sets whether default exclusions should be used or not.
@@ -269,14 +311,41 @@ public class Javadoc extends Task {
         cmd.createArgument().setFile(destDir);
     }
     public void setSourcefiles(String src) {
-        sourceFiles = src;
+        StringTokenizer tok = new StringTokenizer(src, ",");
+        while (tok.hasMoreTokens()) {
+            String f = tok.nextToken();
+            SourceFile sf = new SourceFile();
+            sf.setFile(project.resolveFile(f));
+            addSource(sf);
+        }
+    }
+    public void addSource(SourceFile sf) {
+        sourceFiles.addElement(sf);
     }
     public void setPackagenames(String src) {
-        packageNames = src;
+        StringTokenizer tok = new StringTokenizer(src, ",");
+        while (tok.hasMoreTokens()) {
+            String p = tok.nextToken();
+            PackageName pn = new PackageName();
+            pn.setName(p);
+            addPackage(pn);
+        }
+    }
+    public void addPackage(PackageName pn) {
+        packageNames.addElement(pn);
     }
 
     public void setExcludePackageNames(String src) {
-        excludePackageNames = src;
+        StringTokenizer tok = new StringTokenizer(src, ",");
+        while (tok.hasMoreTokens()) {
+            String p = tok.nextToken();
+            PackageName pn = new PackageName();
+            pn.setName(p);
+            addExcludePackage(pn);
+        }
+    }
+    public void addExcludePackage(PackageName pn) {
+        excludePackageNames.addElement(pn);
     }
 
     public void setOverview(File f) {
@@ -297,6 +366,9 @@ public class Javadoc extends Task {
     public void setPrivate(boolean b) {
         addArgIf(b, "-private");
     }
+    public void setAccess(AccessType at) {
+        cmd.createArgument().setValue("-" + at.getValue());
+    }
     public void setDoclet(String src) {
         if (doclet == null) {
             doclet = new DocletInfo();
@@ -403,20 +475,45 @@ public class Javadoc extends Task {
         add12ArgIfNotEmpty("-windowtitle", src);
     }
     public void setDoctitle(String src) {
-        add12ArgIfNotEmpty("-doctitle", src);
+        Html h = new Html();
+        h.addText(src);
+        addDoctitle(h);
+    }
+    public void addDoctitle(Html text) {
+        if (!javadoc1) {
+            doctitle = text;
+        }
     }
     public void setHeader(String src) {
-        add12ArgIfNotEmpty("-header", src);
+        Html h = new Html();
+        h.addText(src);
+        addHeader(h);
+    }
+    public void addHeader(Html text) {
+        if (!javadoc1) {
+            header = text;
+        }
     }
-
     public void setFooter(String src) {
-        add12ArgIfNotEmpty("-footer", src);
+        Html h = new Html();
+        h.addText(src);
+        addFooter(h);
+    }
+    public void addFooter(Html text) {
+        if (!javadoc1) {
+            footer = text;
+        }
     }
-
     public void setBottom(String src) {
-        add12ArgIfNotEmpty("-bottom", src);
+        Html h = new Html();
+        h.addText(src);
+        addBottom(h);
+    }
+    public void addBottom(Html text) {
+        if (!javadoc1) {
+            bottom = text;
+        }
     }
-
     public void setLinkoffline(String src) {
         if (!javadoc1) {
             LinkArgument le = createLink();
@@ -531,7 +628,8 @@ public class Javadoc extends Task {
 
     public class GroupArgument {
         private String title;
-        private String packages;
+        private Html title2;
+        private Vector packages = new Vector(3);
 
         public GroupArgument() {
         }
@@ -539,17 +637,38 @@ public class Javadoc extends Task {
         public void setTitle(String src) {
             title = src;
         }
+        public void addTitle(Html text) {
+            title2 = text;
+        }
 
         public String getTitle() {
-            return title;
+            return title2 != null ? title2.getText() : title;
         }
 
         public void setPackages(String src) {
-            packages = src;
+            StringTokenizer tok = new StringTokenizer(src, ",");
+            while (tok.hasMoreTokens()) {
+                String p = tok.nextToken();
+                PackageName pn = new PackageName();
+                pn.setName(p);
+                addPackage(pn);
+            }
+        }
+        public void addPackage(PackageName pn) {
+            packages.addElement(pn);
         }
 
         public String getPackages() {
-            return packages;
+            String p = null;
+            for (int i = 0; i < packages.size(); i++) {
+                PackageName pn = (PackageName)packages.elementAt(i);
+                if (p == null || p.equals("")) {
+                    p = pn.getName();
+                } else {
+                    p += ":" + pn.getName();
+                }
+            }
+            return p;
         }
     }
     
@@ -579,6 +698,23 @@ public class Javadoc extends Task {
 
         log("Generating Javadoc", Project.MSG_INFO);
 
+        if (doctitle != null) {
+            cmd.createArgument().setValue("-doctitle");
+            cmd.createArgument().setValue(doctitle.getText());
+        }
+        if (header != null) {
+            cmd.createArgument().setValue("-header");
+            cmd.createArgument().setValue(header.getText());
+        }
+        if (footer != null) {
+            cmd.createArgument().setValue("-footer");
+            cmd.createArgument().setValue(footer.getText());
+        }
+        if (bottom != null) {
+            cmd.createArgument().setValue("-bottom");
+            cmd.createArgument().setValue(bottom.getText());
+        }
+
         Commandline toExecute = (Commandline)cmd.clone();
         toExecute.setExecutable("javadoc");
 
@@ -715,11 +851,12 @@ public class Javadoc extends Task {
 
         }
 
-        if ((packageNames != null) && (packageNames.length() > 0)) {
+        if (packageNames.size() > 0) {
             Vector packages = new Vector();
-            StringTokenizer tok = new StringTokenizer(packageNames, ",", false);
-            while (tok.hasMoreTokens()) {
-                String name = tok.nextToken().trim();
+            Enumeration enum = packageNames.elements();
+            while (enum.hasMoreElements()) {
+                PackageName pn = (PackageName) enum.nextElement();
+                String name = pn.getName().trim();
                 if (name.endsWith(".*")) {
                     packages.addElement(name);
                 } else {
@@ -728,10 +865,11 @@ public class Javadoc extends Task {
             }
 
             Vector excludePackages = new Vector();
-            if ((excludePackageNames != null) && (excludePackageNames.length() > 0)) {
-                StringTokenizer exTok = new StringTokenizer(excludePackageNames, ",", false);
-                while (exTok.hasMoreTokens()) {
-                    excludePackages.addElement(exTok.nextToken().trim());
+            if (excludePackageNames.size() > 0) {
+                enum = excludePackageNames.elements();
+                while (enum.hasMoreElements()) {
+                    PackageName pn = (PackageName) enum.nextElement();
+                    excludePackages.addElement(pn.getName().trim());
                 }
             }
             if (packages.size() > 0) {
@@ -739,10 +877,11 @@ public class Javadoc extends Task {
             }
         }
 
-        if ((sourceFiles != null) && (sourceFiles.length() > 0)) {
-            StringTokenizer tok = new StringTokenizer(sourceFiles, ",", false);
-            while (tok.hasMoreTokens()) {
-                toExecute.createArgument().setValue(tok.nextToken().trim());
+        if (sourceFiles.size() > 0) {
+            Enumeration enum = sourceFiles.elements();
+            while (enum.hasMoreElements()) {
+                SourceFile sf = (SourceFile) enum.nextElement();
+                toExecute.createArgument().setValue(sf.getFile().getAbsolutePath());
             }
         }