This patch lets more options to <javadoc> be specified as nested elements
rather than attributes. Docs patch included.
For one thing, nested elements permit text content model, which makes it much
clearer to specify complex or lengthy HTML text in e.g. the -footer argument.
Instead of:
<javadoc ... footer="<b>Text...</b>"/>
you can have:
<javadoc ...>
<footer><![CDATA[
<b>Text...</b>
]]></footer>
</javadoc>
For another thing, many complicated options otherwise require un-XML-like
arbitrary syntax: lists of strings separated by commas, colons, etc. Now you
can list each parameter as a subelement, which could be clearer to some
tastes. E.g. rather than:
<javadoc ... packages="foo,bar"/>
you can have:
<javadoc>
<package name="foo"/>
<package name="bar"/>
</javadoc>
This may also be useful for <source file="resolved/by/Basedir.java"/>.
Third, rather than e.g. private="true", you can specify access="private" or
similar, with an enumerated list of values for 'access', which is probably
more intuitive.
Tested only casually, but seems to work. Attaching sample build file showing
before and after versions. A test case for <javadoc> might be useful but I am
not sure what exactly it ought to test.
-Jesse
--
Jesse Glick <mailto:[EMAIL PROTECTED]>
NetBeans, Open APIs <http://www.netbeans.org/>
tel (+4202) 3300-9161 Sun Micro x49161 Praha CRIndex: docs/manual/CoreTasks/javadoc.html
===================================================================
RCS file: /home/cvspublic/jakarta-ant/docs/manual/CoreTasks/javadoc.html,v
retrieving revision 1.6
diff -u -t -r1.6 javadoc.html
--- docs/manual/CoreTasks/javadoc.html 2001/04/18 14:49:50 1.6
+++ docs/manual/CoreTasks/javadoc.html 2001/05/03 20:27:21
@@ -75,7 +75,8 @@
<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><source></code> or <code><package></code></td>
</tr>
<tr>
<td valign="top">packagenames</td>
@@ -130,6 +131,13 @@
<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>
<td align="center" valign="top">all</td>
@@ -382,13 +390,71 @@
</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><doctitle></code>.</p>
+
+<h4>footer</h4>
+
+<p>Similar to <code><doctitle></code>.</p>
+
+<h4>bottom</h4>
+
+<p>Similar to <code><doctitle></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 @@
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 @@
<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><title></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><package></code>s given</td>
</tr>
</table>
+<p>The title may be specified as a nested <code><title></code> element
+with text contents, and the packages may be listed with nested
+<code><package></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 @@
author="true"
version="true"
use="true"
- windowtitle="Test API"
- doctitle="<h1>Test</h1>"
- bottom="<i>Copyright &#169; 2000 Dummy Corp. All
Rights Reserved.</i>">
+ windowtitle="Test API">
+
<doctitle><![CDATA[<h1>Test</h1>]]></doctitle>
+ <bottom><![CDATA[<i>Copyright &#169; 2000 Dummy Corp.
All Rights Reserved.</i>]]></bottom>
<group title="Group 1 Packages"
packages="com.dummy.test.a*"/>
<group title="Group 2 Packages"
packages="com.dummy.test.b*:com.dummy.test.c*"/>
<link offline="true"
href="http://java.sun.com/products/jdk/1.2/docs/api/"
packagelistLoc="C:\tmp"/>
Index: src/main/org/apache/tools/ant/taskdefs/Javadoc.java
===================================================================
RCS file:
/home/cvspublic/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/Javadoc.java,v
retrieving revision 1.46
diff -u -t -r1.46 Javadoc.java
--- src/main/org/apache/tools/ant/taskdefs/Javadoc.java 2001/04/18 14:49:52
1.46
+++ src/main/org/apache/tools/ant/taskdefs/Javadoc.java 2001/05/03 20:27:35
@@ -164,6 +164,44 @@
}
}
+ 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);
@@ -205,8 +243,11 @@
private Path sourcePath = null;
private File destDir = null;
private String sourceFiles = null;
+ private Vector sourceFiles2 = new Vector();
private String packageNames = null;
+ private Vector packageNames2 = new Vector(5);
private String excludePackageNames = null;
+ private Vector excludePackageNames2 = new Vector(1);
private boolean author = true;
private boolean version = true;
private DocletInfo doclet = null;
@@ -218,6 +259,10 @@
private Vector links = new Vector(2);
private Vector groups = new Vector(2);
private boolean useDefaultExcludes = true;
+ private Html doctitle2 = null;
+ private Html header2 = null;
+ private Html footer2 = null;
+ private Html bottom2 = null;
/**
* Sets whether default exclusions should be used or not.
@@ -271,13 +316,22 @@
public void setSourcefiles(String src) {
sourceFiles = src;
}
+ public void addSource(SourceFile sf) {
+ sourceFiles2.addElement(sf);
+ }
public void setPackagenames(String src) {
packageNames = src;
}
+ public void addPackage(PackageName pn) {
+ packageNames2.addElement(pn);
+ }
public void setExcludePackageNames(String src) {
excludePackageNames = src;
}
+ public void addExcludePackage(PackageName pn) {
+ excludePackageNames2.addElement(pn);
+ }
public void setOverview(File f) {
if (!javadoc1) {
@@ -297,6 +351,9 @@
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();
@@ -405,18 +462,35 @@
public void setDoctitle(String src) {
add12ArgIfNotEmpty("-doctitle", src);
}
+ public void addDoctitle(Html text) {
+ if (!javadoc1) {
+ doctitle2 = text;
+ }
+ }
public void setHeader(String src) {
add12ArgIfNotEmpty("-header", src);
}
-
+ public void addHeader(Html text) {
+ if (!javadoc1) {
+ header2 = text;
+ }
+ }
public void setFooter(String src) {
add12ArgIfNotEmpty("-footer", src);
}
-
+ public void addFooter(Html text) {
+ if (!javadoc1) {
+ footer2 = text;
+ }
+ }
public void setBottom(String src) {
add12ArgIfNotEmpty("-bottom", src);
}
-
+ public void addBottom(Html text) {
+ if (!javadoc1) {
+ bottom2 = text;
+ }
+ }
public void setLinkoffline(String src) {
if (!javadoc1) {
LinkArgument le = createLink();
@@ -531,7 +605,9 @@
public class GroupArgument {
private String title;
- private String packages;
+ private Html title2;
+ private String packages = null;
+ private Vector packages2 = new Vector(3);
public GroupArgument() {
}
@@ -539,17 +615,32 @@
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;
}
+ public void addPackage(PackageName pn) {
+ packages2.addElement(pn);
+ }
public String getPackages() {
- return packages;
+ String p = packages;
+ for (int i = 0; i < packages2.size(); i++) {
+ PackageName pn = (PackageName)packages2.elementAt(i);
+ if (p == null || p.equals("")) {
+ p = pn.getName();
+ } else {
+ p += ":" + pn.getName();
+ }
+ }
+ return p;
}
}
@@ -578,6 +669,48 @@
}
log("Generating Javadoc", Project.MSG_INFO);
+
+ // Process nested element syntax.
+ for (int i = 0; i < packageNames2.size(); i++) {
+ PackageName pn = (PackageName)packageNames2.elementAt(i);
+ if (packageNames == null || packageNames.equals("")) {
+ packageNames = pn.getName();
+ } else {
+ packageNames += "," + pn.getName();
+ }
+ }
+ for (int i = 0; i < excludePackageNames2.size(); i++) {
+ PackageName pn = (PackageName)excludePackageNames2.elementAt(i);
+ if (excludePackageNames == null || excludePackageNames.equals(""))
{
+ excludePackageNames = pn.getName();
+ } else {
+ excludePackageNames += "," + pn.getName();
+ }
+ }
+ for (int i = 0; i < sourceFiles2.size(); i++) {
+ SourceFile sf = (SourceFile)sourceFiles2.elementAt(i);
+ if (sourceFiles == null || sourceFiles.equals("")) {
+ sourceFiles = sf.getFile().getAbsolutePath();
+ } else {
+ sourceFiles += "," + sf.getFile().getAbsolutePath();
+ }
+ }
+ if (doctitle2 != null) {
+ cmd.createArgument().setValue("-doctitle");
+ cmd.createArgument().setValue(doctitle2.getText());
+ }
+ if (header2 != null) {
+ cmd.createArgument().setValue("-header");
+ cmd.createArgument().setValue(header2.getText());
+ }
+ if (footer2 != null) {
+ cmd.createArgument().setValue("-footer");
+ cmd.createArgument().setValue(footer2.getText());
+ }
+ if (bottom2 != null) {
+ cmd.createArgument().setValue("-bottom");
+ cmd.createArgument().setValue(bottom2.getText());
+ }
Commandline toExecute = (Commandline)cmd.clone();
toExecute.setExecutable("javadoc");
<project name="javadoctest" default="all">
<target name="all">
<mkdir dir="/tmp/javadoctest"/>
<!--
<javadoc
packagenames="org.openidex.filesystems,org.openidex.projects,org.openidex.util,org.openidex.jarpackager"
destdir="/tmp/javadoctest"
doctitle="<table><tr><td>Some</td><td>random</td></tr><tr><td>tabular</td><td>nonsense</td></tr></table>"
header="Some <u>bold</u> text"
footer="Some more <u>bold</u> text"
private="true"
bottom="<i>Copyright © 2000 Dummy Corp. All Rights
Reserved.</i>">
<group title="FS & Projects Stuff"
packages="org.openidex.filesystems:org.openidex.projects"/>
<group title="Some <em>random</em> utils..."
packages="org.openidex.util"/>
<sourcepath>
<pathelement location="/space/src/nb_all/openidex/src"/>
</sourcepath>
<classpath>
<fileset dir="/space/src/nb_all/openide/netbeans/lib">
<include name="openide*.jar"/>
</fileset>
</classpath>
</javadoc>
-->
<javadoc destdir="/tmp/javadoctest" access="private">
<package name="org.openidex.filesystems"/>
<package name="org.openidex.projects"/>
<package name="org.openidex.util"/>
<package name="org.openidex.jarpackager"/>
<doctitle><![CDATA[
<table><tr><td>Some</td><td>random</td></tr><tr><td>tabular</td><td>nonsense</td></tr></table>
]]></doctitle>
<header><![CDATA[
Some <u>bold</u> text
]]></header>
<footer><![CDATA[
Some more <u>bold</u> text
]]></footer>
<bottom><![CDATA[
<i>Copyright © 2000 Dummy Corp. All Rights Reserved.</i>
]]></bottom>
<group>
<title><![CDATA[
FS & Projects Stuff
]]></title>
<package name="org.openidex.filesystems"/>
<package name="org.openidex.projects"/>
</group>
<group>
<title><![CDATA[
Some <em>random</em> utils...
]]></title>
<package name="org.openidex.util"/>
</group>
<sourcepath>
<pathelement location="/space/src/nb_all/openidex/src"/>
</sourcepath>
<classpath>
<fileset dir="/space/src/nb_all/openide/netbeans/lib">
<include name="openide*.jar"/>
</fileset>
</classpath>
</javadoc>
</target>
</project>
