ehatcher 2003/03/04 19:03:11
Modified: . WHATSNEW
docs/manual/CoreTasks javadoc.html
src/main/org/apache/tools/ant/taskdefs Javadoc.java
Log:
#17142 - enhance Javadoc tag element to allow a fileset
Revision Changes Path
1.359 +3 -0 ant/WHATSNEW
Index: WHATSNEW
===================================================================
RCS file: /home/cvs/ant/WHATSNEW,v
retrieving revision 1.358
retrieving revision 1.359
diff -u -r1.358 -r1.359
--- WHATSNEW 24 Feb 2003 08:25:18 -0000 1.358
+++ WHATSNEW 5 Mar 2003 03:03:11 -0000 1.359
@@ -234,6 +234,9 @@
possible to save the output into a property for use within the build
file as was possible with <exec> in Ant 1.5
+* The <javadoc> task <tag> subelement has been enhanced to allow files
+ with tag mappings to be used.
+
Changes from Ant 1.5.1Beta1 to 1.5.1
====================================
1.23 +46 -29 ant/docs/manual/CoreTasks/javadoc.html
Index: javadoc.html
===================================================================
RCS file: /home/cvs/ant/docs/manual/CoreTasks/javadoc.html,v
retrieving revision 1.22
retrieving revision 1.23
diff -u -r1.22 -r1.23
--- javadoc.html 8 Nov 2002 16:10:12 -0000 1.22
+++ javadoc.html 5 Mar 2003 03:03:11 -0000 1.23
@@ -22,16 +22,16 @@
1.2 and 1.4), 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(), javadoc cannot be run inside the
-same VM as ant without breaking functionality. For this reason, this task
+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
+<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>
<p><i><b>DEPRECATION:</b> the javadoc2 task simply points to the javadoc
task and it's
@@ -462,7 +462,7 @@
<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>
@@ -523,7 +523,7 @@
</tr>
<tr>
<td valign="top">offline</td>
- <td valign="top">True if this link is not available online at the time
of
+ <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>
@@ -534,8 +534,8 @@
<td align="center" valign="top">Only if the offline attribute is
true</td>
</tr>
</table>
-
-<h4><a name="groupelement">group</a></h4>
+
+<h4><a name="groupelement">group</a></h4>
<p>Separates packages on the overview page into whatever groups you
specify, one group per table. This performs the same role as the group
attribute. You can use either syntax (or both at once), but with the
@@ -566,15 +566,15 @@
<code><package></code> elements as for the main task.</p>
<h4>doclet</h4>
-<p>The doclet nested element is used to specify the doclet that javadoc will
+<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
are actually arguments of the standard doclet. If these are specified in the
javadoc
-task's attributes, they will be passed to the doclet specified in the
-<code><doclet></code> nested element. Such attributes should only be
specified,
+task's attributes, they will be passed to the doclet specified in the
+<code><doclet></code> nested element. Such attributes should only be
specified,
therefore, if they can be interpreted by the doclet in use.</p>
<p>If the doclet requires additional parameters, these can be specified with
-<code><param></code> elements within the <code><doclet></code>
+<code><param></code> elements within the <code><doclet></code>
element. These paramaters are restricted to simple strings. An example usage
of the doclet element is shown below:</p>
@@ -587,7 +587,7 @@
</javadoc>
</pre>
-<h4><a name="tagelement">tag</a></h4>
+<h4><a name="tagelement">tag</a></h4>
<p>The tag nested element is used to specify custom tags. This option
is only available with Java 1.4.</p>
@@ -602,12 +602,12 @@
<tr>
<td valign="top">name</td>
<td valign="top">Name of the tag (e.g. <code>todo</code>)</td>
- <td align="center" valign="top">Yes</td>
+ <td align="center" valign="top">Yes, unless the <code>dir</code>
attribute is specified.</td>
</tr>
<tr>
<td valign="top">description</td>
<td valign="top">Description for tag (e.g. <code>To do:</code>)</td>
- <td align="center" valign="top">Yes</td>
+ <td align="center" valign="top">Yes, unless the <code>dir</code>
attribute is specified.</td>
</tr>
<tr>
<td valign="top">enabled</td>
@@ -617,15 +617,32 @@
<tr>
<td valign="top">scope</td>
<td valign="top">Scope for the tag - the elements in which it can be
used. This
- is a comma separated list of some of the elements:
<code>overview</code>,
- <code>packages</code>, <code>types</code>, <code>constructors</code>,
+ is a comma separated list of some of the elements: <code>overview</code>,
+ <code>packages</code>, <code>types</code>, <code>constructors</code>,
<code>methods</code>, <code>fields</code> or the default,
<code>all</code>.</td>
<td align="center" valign="top">No</td>
</tr>
+ <tr>
+ <td valign="top">dir</td>
+ <td valign="top">If this attribute is specified, this element will
behave as an implicit
+ <a href="../CoreTypes/fileset.html">fileset</a>. The files included by
this fileset should
+ contain each tag definition on a separate line, as described in the
+ <a
href="http://java.sun.com/j2se/1.4.1/docs/tooldocs/windows/javadoc.html#tag";>javadoc
reference guide</a>:
+ <p/>
+ <code>
+ ejb.bean:t:"XDoclet EJB Tag"<br/>
+ todo:a:"To Do"<br/>
+ </code>
+ <p/>
+ Note: If this attribute is specified, all the other attributes in this
+ element will be ignored.
+ </td>
+ <td align="center" valign="top">No</td>
+ </tr>
</table>
-<h4><a name="tagletelement">taglet</a></h4>
-<p>The taglet nested element is used to specify custom taglets. This option
is
+<h4><a name="tagletelement">taglet</a></h4>
+<p>The taglet nested element is used to specify custom taglets. This option
is
only available with Java 1.4.</p>
<h5>Parameters</h5>
@@ -637,7 +654,7 @@
</tr>
<tr>
<td valign="top">name</td>
- <td valign="top">The name of the taglet class
+ <td valign="top">The name of the taglet class
(e.g. <code>com.sun.tools.doclets.ToDoTaglet</code>)</td>
<td align="center" valign="top">Yes</td>
</tr>
@@ -675,10 +692,10 @@
<link offline="true"
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/"/>
</javadoc></pre>
-
+
<p>is the same as</p>
-<pre> <javadoc
+<pre> <javadoc
destdir="docs/api"
author="true"
version="true"
@@ -700,8 +717,8 @@
</javadoc></pre>
<p>or</p>
-
-<pre> <javadoc
+
+<pre> <javadoc
destdir="docs/api"
author="true"
version="true"
@@ -723,7 +740,7 @@
</javadoc></pre>
<hr>
-<p align="center">Copyright © 2000-2002 Apache Software Foundation. All
rights
+<p align="center">Copyright © 2000-2003 Apache Software Foundation. All
rights
Reserved.</p>
</body>
1.109 +30 -4 ant/src/main/org/apache/tools/ant/taskdefs/Javadoc.java
Index: Javadoc.java
===================================================================
RCS file: /home/cvs/ant/src/main/org/apache/tools/ant/taskdefs/Javadoc.java,v
retrieving revision 1.108
retrieving revision 1.109
diff -u -r1.108 -r1.109
--- Javadoc.java 19 Feb 2003 12:30:55 -0000 1.108
+++ Javadoc.java 5 Mar 2003 03:03:11 -0000 1.109
@@ -58,6 +58,8 @@
import java.io.FilenameFilter;
import java.io.IOException;
import java.io.PrintWriter;
+import java.io.BufferedReader;
+import java.io.FileReader;
import java.net.MalformedURLException;
import java.net.URL;
import java.util.Enumeration;
@@ -1244,7 +1246,7 @@
/**
* Class representing a -tag argument.
*/
- public class TagArgument {
+ public class TagArgument extends FileSet {
/** Name of the tag. */
private String name = null;
/** Description of the tag to place in the JavaDocs. */
@@ -1468,7 +1470,7 @@
*/
public void setSource(String source) {
if (!javadoc4) {
- log ("-source option not supported on JavaDoc < 1.4",
+ log ("-source option not supported on JavaDoc < 1.4",
Project.MSG_VERBOSE);
}
this.source = source;
@@ -1744,8 +1746,32 @@
Object element = e.nextElement();
if (element instanceof TagArgument) {
TagArgument ta = (TagArgument) element;
- toExecute.createArgument().setValue ("-tag");
- toExecute.createArgument().setValue
(ta.getParameter());
+ File tagDir = ta.getDir(getProject());
+ if (tagDir == null ) {
+ // The tag element is not used as a fileset,
+ // but specifies the tag directly.
+ toExecute.createArgument().setValue ("-tag");
+ toExecute.createArgument().setValue
(ta.getParameter());
+ } else {
+ // The tag element is used as a fileset. Parse
all the files and
+ // create -tag arguments.
+ DirectoryScanner tagDefScanner =
ta.getDirectoryScanner(getProject());
+ String[] files =
tagDefScanner.getIncludedFiles();
+ for (int i = 0; i < files.length; i++) {
+ File tagDefFile = new File( tagDir, files[i]
);
+ try {
+ BufferedReader in = new BufferedReader(
new FileReader(tagDefFile) );
+ String line = null;
+ while( (line = in.readLine()) != null ) {
+ toExecute.createArgument().setValue
("-tag");
+ toExecute.createArgument().setValue
(line);
+ }
+ in.close();
+ } catch( IOException ioe ) {
+ throw new BuildException( "Couldn't read
tag file from " + tagDefFile.getAbsolutePath(), ioe );
+ }
+ }
+ }
} else {
ExtensionInfo tagletInfo = (ExtensionInfo) element;
toExecute.createArgument().setValue("-taglet");
