As per Wolgang's request, I resend the javadoc patch I had already sent
a month ago.
The new syntax is not backward compatible with the old one, but this can
be easily changed by changing the names of the child elements link,
linoffline and group.
P@
--
Patrick Chanezon, Vortex - Portal/EServices Technical Lead
Netscape Communications Corp. - http://people.netscape.com/chanezon/
Opinions are my own.
"Two monks were arguing about a flag. One said: `The flag is moving.'
The other said: `The wind is moving.'
The sixth patriach happened to be passing by. He told them: `Not the
wind, not the flag; mind is moving.'"
Zen Koan
--- Begin Message ---
Hi Ant users and developers,
I enhanced the javadoc task in order to make full use of some javadoc
features as descibed in
http://jakarta.apache.org/bugs/show_bug.cgi?id=64
which means:
* support for multiple link and linkoffline options
* support for multiple group options
* support for the @ argument
I submitted such a patch the 3/13 but it used an ugly hack involving a
separator to specify multiple arguments.
This patch takes into account the input I received from the Ant
developers in this list: Stefano Mazzocchi and Sam Ruby.
I implemented the link, linkoffline and group arguments not as
attributes of the task but as subelements.
The new syntax looks like:
<javadoc packagenames="com.dummy.test.*"
sourcepath="src"
destdir="docs/api"
author="true"
version="true"
use="true"
windowtitle="Test API"
doctitle="<h1>Test</h1>"
bottom="<i>Copyright © 2000 Dummy Corp. All Rights
Reserved.</i>"/>
<linkoffline
href="http://java.sun.com/products/jdk/1.2/docs/api/";
packagelistLoc="C:\tmp"/>
<link
href="http://developer.java.sun.com/developer/products/xml/docs/api/"/>
<group title="Group 1 Packages"
packages="com.dummy.test.a*"/>
<group title="Group 2 Packages"
packages="com.dummy.test.b*"/>
</javadoc>
This fixes as well the problem noticed by Scott Came in that list the
3/21.
Thus, the syntax for the task changes: I was not able to maintain
backward compatibility.
If this is an issue, I am open to suggestions about how to maintain it.
The issue is: it seems that the attribute names and the entity names
should be different (else I get a nullPointerException), so I'll have to
change the name of the new options. If this proves to be a problem, and
if you vote for it, I can do that.
I modified the documentation as well.
One question about it: what tool do you use to edit the HTML
documentation ? I edited it in Composer, then added the HTML manually in
order not to pollute it too much with Composer junk.
I hope you'll like this patch.
P@
--
Patrick Chanezon, Vortex - Portal/EServices Technical Lead
Netscape Communications Corp. - http://people.netscape.com/chanezon/
Opinions are my own.
"Two monks were arguing about a flag. One said: `The flag is moving.'
The other said: `The wind is moving.'
The sixth patriach happened to be passing by. He told them: `Not the
wind, not the flag; mind is moving.'"
Zen Koan
Index: Javadoc.java
===================================================================
RCS file:
/home/cvspublic/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/Javadoc.java,v
retrieving revision 1.7
diff -u -r1.7 Javadoc.java
--- Javadoc.java 2000/03/03 14:15:42 1.7
+++ Javadoc.java 2000/03/28 03:23:45
@@ -75,6 +75,16 @@
*
* @author Jon S. Stevens <a href="mailto:[EMAIL PROTECTED]">[EMAIL
PROTECTED]</a>
* @author Stefano Mazzocchi <a href="mailto:[EMAIL PROTECTED]">[EMAIL
PROTECTED]</a>
+ * @author Patrick Chanezon <a href="mailto:[EMAIL PROTECTED]">[EMAIL
PROTECTED]</a>
+ * I enhanced the task as described in
http://jakarta.apache.org/bugs/show_bug.cgi?id=64
+ * which means:
+ * support for multiple link options
+ * support for multiple group options
+ * support for @
+ * - link and linkoffline: you can now list more than one -link option.
+ * the link and linkoffline are no more attributes of the task but
subelements
+ * - group: same remark, you can now list more than one -group option
+ * - the COMMAND LINE ARGUMENT FILE syntax: javadoc -d apidocs @packages is
now supported with the packagelist tag
*/
public class Javadoc extends Exec {
@@ -106,7 +116,6 @@
private String header = null;
private String footer = null;
private String bottom = null;
- private String link = null;
private String linkoffline = null;
private String group = null;
private boolean nodeprecated = false;
@@ -119,6 +128,10 @@
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 linkofflines = new Vector(2);
+ private Vector groups = new Vector(2);
public void setSourcepath(String src) {
sourcePath = project.translatePath(src);
@@ -201,9 +214,6 @@
public void setBottom(String src) {
bottom = src;
}
- public void setLink(String src) {
- link = src;
- }
public void setLinkoffline(String src) {
linkoffline = src;
}
@@ -234,6 +244,77 @@
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 {
+ public LinkArgument() {
+ }
+ private String href;
+ public void setHref(String hr) {
+ href = hr;
+ }
+ public String getHref() {
+ return href;
+ }
+ }
+
+ public LinkofflineArgument createLinkoffline() {
+ LinkofflineArgument loa = new LinkofflineArgument();
+ linkofflines.addElement(loa);
+ return loa;
+ }
+
+ public class LinkofflineArgument {
+ public LinkofflineArgument() {
+ }
+ private String href;
+ private String packagelistLoc;
+ 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 GroupArgument createGroup() {
+ GroupArgument ga = new GroupArgument();
+ groups.addElement(ga);
+ return ga;
+ }
+
+ public class GroupArgument {
+ public GroupArgument() {
+ }
+ private String title;
+ private String packages;
+ 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 ) {
@@ -357,19 +438,64 @@
if (bottom != null) {
argList.addElement("-bottom");
argList.addElement(bottom);
+ }
+
+ // add the link arguments
+ if (links.size() != 0) {
+ String href = null;
+ LinkArgument la = null;
+ for (int i = 0; i < links.size(); i++) {
+ la = (LinkArgument)links.get(i);
+ if (la != null) {
+ href = la.getHref();
+ }
+ if (href != null) {
+ argList.addElement("-link");
+ argList.addElement(href);
+ }
+ }
}
- if (link != null) {
- argList.addElement("-link");
- argList.addElement(link);
- }
- if (linkoffline != null) {
- argList.addElement("-linkoffline");
- argList.addElement(linkoffline);
- }
- if (group != null) {
- argList.addElement("-group");
- argList.addElement(group);
+
+ // add the linkoffline arguments
+ if (linkofflines.size() != 0) {
+ String href = null;
+ String packagelistLoc = null;
+ LinkofflineArgument loa = null;
+ for (int i = 0; i < linkofflines.size(); i++) {
+ loa = (LinkofflineArgument)linkofflines.get(i);
+ if (loa != null) {
+ href = loa.getHref();
+ packagelistLoc = loa.getPackagelistLoc();
+ }
+ if ((href != null) && (packagelistLoc != null)) {
+ argList.addElement("-linkoffline");
+ argList.addElement(href);
+ argList.addElement(packagelistLoc);
+ }
+ }
}
+
+ // 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");
argList.addElement(stylesheetfile.getAbsolutePath());
@@ -403,6 +529,9 @@
}
}
+ if (packageList != null) {
+ argList.addElement("@" + packageList);
+ }
project.log("Javadoc args: " + argList.toString(), "javadoc",
project.MSG_VERBOSE);
project.log("Javadoc execution", project.MSG_INFO);
Index: index.html
===================================================================
RCS file: /home/cvspublic/jakarta-ant/docs/index.html,v
retrieving revision 1.15
diff -u -r1.15 index.html
--- index.html 2000/03/23 03:40:32 1.15
+++ index.html 2000/03/28 03:26:17
@@ -1387,6 +1387,15 @@
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>WARNING: 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 convert from an existing makefile, to get
+things running, and then switch to the regular notation when your project
+is in a more stable state.</p>
<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>
@@ -1424,6 +1433,12 @@
<td align="center" valign="top">all</td>
</tr>
<tr>
+ <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>
@@ -1551,25 +1566,6 @@
<td align="center" valign="top">No</td>
</tr>
<tr>
- <td valign="top">link</td>
- <td valign="top">Create links to javadoc output at the given URL</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">linkoffline</td>
- <td valign="top">Link to docs at <url> using package list at
- <url2></td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">group</td>
- <td valign="top">Group specified packages together in overview page</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
<td valign="top">nodeprecated</td>
<td valign="top">Do not include @deprecated information</td>
<td align="center" valign="top">all</td>
@@ -1637,6 +1633,104 @@
<td align="center" valign="top">No</td>
</tr>
</table>
+<h3>
+Parameters specified as subelements</h3>
+3 parameters of the Javadoc task must be specified as subelements of the
+Task element.
+<br>These parameters are not required and can have many occurences.
+<h4>
+link</h4>
+Create links to javadoc output at the given URL
+<h4>
+Parameters</h4>
+
+<table 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 to link to.</td>
+
+<td ALIGN=CENTER VALIGN=TOP>Yes</td>
+</tr>
+</table>
+
+<h4>
+linkoffline</h4>
+Link to docs at <href> using package list at <packagelistLoc>
+<br>Create links to javadoc output at the given URL
+<h4>
+Parameters</h4>
+
+<table 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 to link to.</td>
+
+<td ALIGN=CENTER VALIGN=TOP>Yes</td>
+</tr>
+
+<tr>
+<td>packagelistLoc</td>
+
+<td>The location to the directory containing the package-list file for
+the external documentation </td>
+
+<td>
+<center>Yes</center>
+</td>
+</tr>
+</table>
+
+<h4>
+group</h4>
+Separates packages on the overview page into whatever groups you specify,
+one group per table.
+<h4>
+Parameters</h4>
+
+<table 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>packages</td>
+
+<td>List of packages to include in that group</td>
+
+<td ALIGN=CENTER VALIGN=TOP>Yes</td>
+</tr>
+</table>
+
<h3>Example</h3>
<pre> <javadoc packagenames="com.dummy.test.*"
sourcepath="src"
@@ -1646,8 +1740,12 @@
use="true"
windowtitle="Test API"
doctitle="<h1>Test</h1>"
- bottom="<i>Copyright &#169; 2000 Dummy Corp. All
Rights Reserved.</i>"
- /></pre>
+ bottom="<i>Copyright &#169; 2000 Dummy Corp. All
Rights Reserved.</i>"/>
+ <linkoffline
href="http://java.sun.com/products/jdk/1.2/docs/api/"; packagelistLoc="C:\tmp"/>
+ <link
href="http://developer.java.sun.com/developer/products/xml/docs/api/"/>
+ <group title="Group 1 Packages" packages="com.dummy.test.a*"/>
+ <group title="Group 2 Packages" packages="com.dummy.test.b*"/>
+ </javadoc></pre>
<hr>
<h2><a name="keysubst">KeySubst</a></h2>
<h3>Description</h3>
begin:vcard
n:Chanezon;Patrick
tel;fax:603.388-9565
tel;work:650.937.6605
x-mozilla-html:TRUE
org:<CENTER><A HREF="http://www.iplanet.com/";><IMG SRC="http://www.iplanet.com/images/header_images/logo.gif"; BORDER=0 </A></CENTER>;Vortex
version:2.1
email;internet:[EMAIL PROTECTED]
title:<I>Vortex - Portal/EServices Technical Lead</I>
note:<A HREF="http://people.netscape.com/chanezon/";><IMG SRC="http://people.netscape.com/chanezon/patrick_photo_identite.jpg"; BORDER=0 HEIGHT=70 WIDTH=49></A><BR>Have Fun with <A HREF="http://www.javasoft.com/";><IMG SRC="http://www.javasoft.com/images/logos/javalogo52x88.gif"; border="0" HEIGHT="88" WIDTH="52"></A><BR><hr><BR>
adr;quoted-printable:;;Netscape Communications Corp.=0D=0A501 E. Middlefield Road=0D=0ABuilding 6=0D=0AMV-025;Mountain View;CA;94043;USA
fn:Patrick Chanezon
end:vcard
--- End Message ---
begin:vcard
n:Chanezon;Patrick
tel;fax:603.388-9565
tel;work:650.937.6605
x-mozilla-html:TRUE
org:<CENTER><A HREF="http://www.iplanet.com/";><IMG SRC="http://www.iplanet.com/images/header_images/logo.gif"; BORDER=0 </A></CENTER>;Vortex
version:2.1
email;internet:[EMAIL PROTECTED]
title:<I>Vortex - Portal/EServices Technical Lead</I>
note:<A HREF="http://people.netscape.com/chanezon/";><IMG SRC="http://people.netscape.com/chanezon/patrick_photo_identite.jpg"; BORDER=0 HEIGHT=70 WIDTH=49></A><BR>Have Fun with <A HREF="http://www.javasoft.com/";><IMG SRC="http://www.javasoft.com/images/logos/javalogo52x88.gif"; border="0" HEIGHT="88" WIDTH="52"></A><BR><hr><BR>
adr;quoted-printable:;;Netscape Communications Corp.=0D=0A501 E. Middlefield Road=0D=0ABuilding 6=0D=0AMV-025;Mountain View;CA;94043;USA
fn:Patrick Chanezon
end:vcard
![http://www.iplanet.com/images/header_images/logo.gif"](http://www.iplanet.com/images/header_images/logo.gif"){kind=link}
![http://people.netscape.com/chanezon/patrick_photo_identite.jpg"](http://people.netscape.com/chanezon/patrick_photo_identite.jpg"){kind=link}
![http://www.javasoft.com/images/logos/javalogo52x88.gif"](http://www.javasoft.com/images/logos/javalogo52x88.gif"){kind=link}