Directory based <javadoc>.

Two new nested elements, <packageset> and <fileset>.  <packageset> is
a DirSet that points to directories which get translated into packages
if they contain .java sources, <fileset> points to sourcefiles.

<packageset> based on a patch by Daniel Ritchey <ritchey_49@hotmail.com>.

<fileset> allows you to select files in the default package as well.

PR: 6433


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

WHATSNEW

@@ -345,6 +345,8 @@ Other changes:
 * <patch> has a new attribute that selects the directory in which to
   run the command.
 
+* <javadoc> now supports two new nested elements, <fileset> and <packageset>.
+
 Changes from Ant 1.4 to Ant 1.4.1
 ===========================================
 

build.xml

@@ -1042,15 +1042,16 @@
           unless="javadoc.notrequired"
           description="--> creates the API documentation">
     <mkdir dir="${build.javadocs}"/>
-    <javadoc packagenames="org.apache.*"
-             useexternalfile="yes"
-             sourcepath="${java.dir}"
+    <javadoc useexternalfile="yes"
              destdir="${build.javadocs}"
              author="true"
              version="true"
              locale="en"
              windowtitle="${Name} API"
              doctitle="${Name}">
+
+      <packageset dir="${java.dir}" />
+
       <tag name="todo" description="To do:" scope="all" />
       <tag name="ant.task" enabled="false" description="Task:" scope="types" />
       <tag name="ant.datatype" enabled="false" description="Data type:" scope="types" />

docs/ant15_todo.html

@@ -295,26 +295,6 @@
     <font color="#000000" size="-1" face="arial,helvetica,sanserif">
           Steve + any other help he can get
         </font>
-  </td>
-      </tr>
-                  <tr>
-                  <td bgcolor="#a0ddf0" colspan="" rowspan="" 
-      valign="top" align="left">
-    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
-          Make javadoc a real directory based task
-        </font>
-  </td>
-                      <td bgcolor="#a0ddf0" colspan="" rowspan="" 
-      valign="top" align="left">
-    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
-          &nbsp;
-        </font>
-  </td>
-                      <td bgcolor="#a0ddf0" colspan="" rowspan="" 
-      valign="top" align="left">
-    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
-          Stefan, others welcome
-        </font>
   </td>
       </tr>
         </table>
@@ -492,6 +472,26 @@
     <font color="#000000" size="-1" face="arial,helvetica,sanserif">
           Stefan
         </font>
+  </td>
+      </tr>
+                  <tr>
+                  <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          Make javadoc a real directory based task
+        </font>
+  </td>
+                      <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          &nbsp;
+        </font>
+  </td>
+                      <td bgcolor="#a0ddf0" colspan="" rowspan="" 
+      valign="top" align="left">
+    <font color="#000000" size="-1" face="arial,helvetica,sanserif">
+          Stefan
+        </font>
   </td>
       </tr>
         </table>

docs/manual/CoreTasks/javadoc.html

@@ -18,9 +18,9 @@ and management costs over time. This task, however, has no notion of
 &quot;changed&quot; files, unlike the <a href="javac.html">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>This task works seamlessly between different javadoc versions (1.1,
+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 
 always forks the VM. This overhead is not significant since javadoc is normally a heavy
@@ -38,6 +38,11 @@ notation. </p>
 there for back compatibility reasons. Since this task will be removed in future
 versions, you are strongly encouraged to use <a href="javadoc.html">javadoc</a>
 instead.</i></p>
+
+<p>In the table below, 1.1 means available if your current Java VM is
+a 1.1 VM, 1.2 for either 1.2 or 1.3 and 1.4 for a 1.4 Java VM.  1.2+
+means any VM of at least version 1.2.</p>
+
 <h3>Parameters</h3>
 <table border="1" cellpadding="2" cellspacing="0">
   <tr>
@@ -50,8 +55,9 @@ instead.</i></p>
     <td valign="top">sourcepath</td>
     <td valign="top">Specify where to find source files</td>
     <td align="center" valign="top">all</td>
-    <td align="center" rowspan="2">At least one of the two or nested
-      <code>&lt;sourcepath&gt;</code></td>
+    <td align="center" rowspan="3">At least one of the three or nested
+    <code>&lt;sourcepath&gt;</code>, <code>&lt;fileset&gt;</code> or
+    <code>&lt;packageset&gt;</code></td>
   </tr>
   <tr>
     <td valign="top">sourcepathref</td>
@@ -59,6 +65,11 @@ instead.</i></p>
       href="../using.html#references">reference</a> to a PATH defined elsewhere.</td>
     <td align="center" valign="top">all</td>
   </tr>
+  <tr>
+    <td valign="top">sourcefiles</td>
+    <td valign="top">Comma separated list of source files</td>
+    <td align="center" valign="top">all</td>
+  </tr>
   <tr>
     <td valign="top">destdir</td>
     <td valign="top">Destination directory for output files</td>
@@ -71,23 +82,17 @@ instead.</i></p>
     <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
-  <tr>
-    <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
-    or nested <code>&lt;source&gt;</code> or <code>&lt;package&gt;</code></td>
-  </tr>
   <tr>
     <td valign="top">packagenames</td>
     <td valign="top">Comma separated list of package files (with terminating
       wildcard)</td>
     <td align="center" valign="top">all</td>
+    <td align="center" valign="top">No</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">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -100,7 +105,7 @@ instead.</i></p>
     <td valign="top">Bootclasspath</td>
     <td valign="top">Override location of class files loaded by the bootstrap
       class loader</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -115,19 +120,19 @@ instead.</i></p>
     <td valign="top">Override location of class files loaded by the
       bootstrap class loader by <a href="../using.html#references">reference</a> to a
       PATH defined elsewhere.</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">Extdirs</td>
     <td valign="top">Override location of installed extensions</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">Overview</td>
     <td valign="top">Read overview documentation from HTML file</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -170,13 +175,13 @@ instead.</i></p>
   <tr>
     <td valign="top">Verbose</td>
     <td valign="top">Output messages about what Javadoc is doing</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">Locale</td>
     <td valign="top">Locale to be used, e.g. en_US or en_US_WIN</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -194,7 +199,7 @@ instead.</i></p>
   <tr>
     <td valign="top">Use</td>
     <td valign="top">Create class and package usage pages</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -206,57 +211,57 @@ instead.</i></p>
   <tr>
     <td valign="top">Splitindex</td>
     <td valign="top">Split index into one file per letter</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">Windowtitle</td>
     <td valign="top">Browser window title for the documentation (text)</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">Doctitle</td>
     <td valign="top">Include title for the package index(first) page (html-code)</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">Header</td>
     <td valign="top">Include header text for each page (html-code)</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">Footer</td>
     <td valign="top">Include footer text for each page (html-code)</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">bottom</td>
     <td valign="top">Include bottom text for each page (html-code)</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">1.2+</td>
     <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">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">linkoffline</td>
     <td valign="top">Link to docs at &lt;url&gt; using package list at
       &lt;url2&gt; - separate the URLs by using a space character.</td>
-    <td align="center" valign="top">1.2</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.  The format is as described <a href="#groupattribute">below</a>.</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -268,7 +273,7 @@ instead.</i></p>
   <tr>
     <td valign="top">nodeprecatedlist</td>
     <td valign="top">Do not generate deprecated list</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -286,56 +291,56 @@ instead.</i></p>
   <tr>
     <td valign="top">nohelp</td>
     <td valign="top">Do not generate help link</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">nonavbar</td>
     <td valign="top">Do not generate navigation bar</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">serialwarn</td>
-    <td valign="top">FUTURE: Generate warning about @serial tag</td>
-    <td align="center" valign="top">1.2</td>
+    <td valign="top">Generate warning about @serial tag</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">helpfile</td>
-    <td valign="top">FUTURE: Specifies the HTML help file to use</td>
-    <td align="center" valign="top">1.2</td>
+    <td valign="top">Specifies the HTML help file to use</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">stylesheetfile</td>
     <td valign="top">Specifies the CSS stylesheet to use</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">charset</td>
-    <td valign="top">FUTURE: Charset for cross-platform viewing of generated
+    <td valign="top">Charset for cross-platform viewing of generated
       documentation</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
     <td valign="top">docencoding</td>
     <td valign="top">Output file encoding name</td>
-    <td align="center" valign="top">1.1</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <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">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">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -343,7 +348,7 @@ instead.</i></p>
     <td valign="top">Specifies the path to the doclet class file that
       is specified with the -doclet option by <a
       href="../using.html#references">reference</a> to a PATH defined elsewhere.</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">1.2+</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -351,7 +356,7 @@ instead.</i></p>
     <td valign="top">Lets you add additional parameters to the javadoc
             command line. Useful for doclets. Parameters containing
             spaces need to be quoted using &amp;quot;.</td>
-    <td align="center" valign="top">1.2</td>
+    <td align="center" valign="top">all</td>
     <td align="center" valign="top">No</td>
   </tr>
   <tr>
@@ -383,7 +388,7 @@ instead.</i></p>
       the package names specified via the packagenames attribute or
       nested package elements.
       (<code>yes</code> | <code>no</code>). Default is no.</td>
-    <td align="center" valign="top">all</td>
+    <td align="center" valign="top">1.2+</td>
     <td valign="top" align="center">No</td>
   </tr>
   <tr>
@@ -412,6 +417,36 @@ recommended.</p>
 
 <h3>Parameters specified as nested elements</h3>
 
+<h4>packageset</h4>
+
+<p>A <a href="../CoreTypes/dirset.html">DirSet</a>.  All matched
+directories that contain Java source files will be passed to javadoc
+as package names.  Package names are created from the directory names
+by translating the directory separator into dots.  Ant assumes the
+base directory of the packageset points to the root of a package
+hierarchy.</p>
+
+<p>The <code>packagenames</code>, <code>excludepackagenames</code> and
+<code>defaultexcludes</code> attributes of the task have no effect on
+the nested <code>&lt;packageset&gt;</code> elements.</p>
+
+<h4>fileset</h4>
+
+<p>A <a href="../CoreTypes/fileset.html">FileSet</a>.  All matched
+files will be passed to javadoc as source files.  Ant will
+automatically add the include pattern <code>**/*.java</code> to these
+filesets.</p>
+
+<p>Nested filesets can be used to document sources that are in the
+default package or if you want to exclude certain files from
+documentation.  If you want to document all source files and don't use
+the default package, packagesets should be used instead as this
+increases javadocs performance.</p>
+
+<p>The <code>packagenames</code>, <code>excludepackagenames</code> and
+<code>defaultexcludes</code> attributes of the task have no effect on
+the nested <code>&lt;fileset&gt;</code> elements.</p>
+
 <h4>package</h4>
 <p>Same as one entry in the list given by <code>packagenames</code>.</p>
 
@@ -554,8 +589,9 @@ of the doclet element is shown below:</p>
 </pre>
 
 <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>
+
+<p>The tag nested element is used to specify custom tags. This option
+is only available with Java 1.4.</p>
 
 <h5>Parameters</h5>
 <table width="60%" border="1" cellpadding="2" cellspacing="0">
@@ -641,6 +677,52 @@ respectively.</p>
     &lt;link href=&quot;http://developer.java.sun.com/developer/products/xml/docs/api/&quot;/&gt;
   &lt/javadoc&gt;</pre>
   
+<p>is the same as</p>
+
+<pre>  &lt;javadoc 
+           destdir=&quot;docs/api&quot;
+           author=&quot;true&quot;
+           version=&quot;true&quot;
+           use=&quot;true&quot;
+           windowtitle=&quot;Test API&quot;&gt;
+
+    &lt;packageset dir=&quot;src&quot; defaultexcludes=&quot;yes&quot;&gt;
+      &lt;include name=&quot;com/dummy/test/**&quot; /&gt;
+      &lt;exclude name=&quot;com/dummy/test/doc-files/**&quot; /&gt;
+    &lt;/packageset&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;tag name=&quot;todo&quot; scope=&quot;all&quot; description=&quot;To do:&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*: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;
+    &lt;link href=&quot;http://developer.java.sun.com/developer/products/xml/docs/api/&quot;/&gt;
+  &lt/javadoc&gt;</pre>
+
+<p>or</p>
+  
+<pre>  &lt;javadoc 
+           destdir=&quot;docs/api&quot;
+           author=&quot;true&quot;
+           version=&quot;true&quot;
+           use=&quot;true&quot;
+           windowtitle=&quot;Test API&quot;&gt;
+
+    &lt;fileset dir=&quot;src&quot; defaultexcludes=&quot;yes&quot;&gt;
+      &lt;include name=&quot;com/dummy/test/**&quot; /&gt;
+      &lt;exclude name=&quot;com/dummy/test/doc-files/**&quot; /&gt;
+    &lt;/fileset&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;tag name=&quot;todo&quot; scope=&quot;all&quot; description=&quot;To do:&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*: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;
+    &lt;link href=&quot;http://developer.java.sun.com/developer/products/xml/docs/api/&quot;/&gt;
+  &lt/javadoc&gt;</pre>
+
 <hr>
 <p align="center">Copyright &copy; 2001-2002 Apache Software Foundation. All rights
 Reserved.</p>

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

@@ -67,11 +67,13 @@ import org.apache.tools.ant.DirectoryScanner;
 import org.apache.tools.ant.Project;
 import org.apache.tools.ant.ProjectComponent;
 import org.apache.tools.ant.Task;
-import org.apache.tools.ant.types.Path;
-import org.apache.tools.ant.types.Reference;
-import org.apache.tools.ant.types.EnumeratedAttribute;
 import org.apache.tools.ant.types.Commandline;
+import org.apache.tools.ant.types.DirSet;
+import org.apache.tools.ant.types.EnumeratedAttribute;
 import org.apache.tools.ant.types.FileSet;
+import org.apache.tools.ant.types.Path;
+import org.apache.tools.ant.types.PatternSet;
+import org.apache.tools.ant.types.Reference;
 import org.apache.tools.ant.util.FileUtils;
 import org.apache.tools.ant.util.JavaEnvUtils;
 
@@ -84,7 +86,6 @@ import org.apache.tools.ant.util.JavaEnvUtils;
  * <P><UL>
  *    <LI>patterns must be of the form "xxx.*", every other pattern doesn't
  *        work.
- *    <LI>the java comment-stripper reader is horribly slow
  *    <LI>there is no control on arguments sanity since they are left
  *        to the javadoc implementation.
  *    <LI>argument J in javadoc1 is not supported (what is that for anyway?)
@@ -281,7 +282,7 @@ public class Javadoc extends Task {
          * @param name the package name.
          */
         public void setName(String name) {
-            this.name = name;
+            this.name = name.trim();
         }
         
         /** 
@@ -308,6 +309,11 @@ public class Javadoc extends Task {
         /** The source file */
         private File file;
         
+        public SourceFile() {}
+        public SourceFile(File file) {
+            this.file = file;
+        }
+
         /**
          * Set the source file.
          *
@@ -375,14 +381,14 @@ public class Javadoc extends Task {
     private Commandline cmd = new Commandline();
     
     /** Flag which indicates if javadoc from JDK 1.1 is to be used. */
-    private static boolean javadoc1 =
-        (JavaEnvUtils.getJavaVersion() == JavaEnvUtils.JAVA_1_1);
+    private static boolean javadoc1 = 
+        JavaEnvUtils.isJavaVersion(JavaEnvUtils.JAVA_1_1);
 
     /** Flag which indicates if javadoc from JDK 1.4 is available */
     private static boolean javadoc4 =
-        (JavaEnvUtils.getJavaVersion() != JavaEnvUtils.JAVA_1_1 &&
-         JavaEnvUtils.getJavaVersion() != JavaEnvUtils.JAVA_1_2 &&
-         JavaEnvUtils.getJavaVersion() != JavaEnvUtils.JAVA_1_3);
+        (!JavaEnvUtils.isJavaVersion(JavaEnvUtils.JAVA_1_1) &&
+         !JavaEnvUtils.isJavaVersion(JavaEnvUtils.JAVA_1_2) &&
+         !JavaEnvUtils.isJavaVersion(JavaEnvUtils.JAVA_1_3));
 
     /**
      * Utility method to add an argument to the command line conditionally
@@ -429,7 +435,8 @@ public class Javadoc extends Task {
     }
 
     /** 
-     * Flag which indicates if the task should fail if there is a javadoc error.
+     * Flag which indicates if the task should fail if there is a
+     * javadoc error.
      */
     private boolean failOnError = false;
     private Path sourcePath = null;
@@ -453,10 +460,12 @@ public class Javadoc extends Task {
     private Html footer = null;
     private Html bottom = null;
     private boolean useExternalFile = false;
-    private File tmpList = null;
     private FileUtils fileUtils = FileUtils.newFileUtils();
     private String source = null;
 
+    private Vector fileSets = new Vector();
+    private Vector packageSets = new Vector();
+
     /**
      * Work around command line length limit by using an external file
      * for the sourcefiles.
@@ -1098,7 +1107,9 @@ public class Javadoc extends Task {
         cmd.createArgument().setValue(enc);
     }
     public void setPackageList(String src) {
-        packageList = src;
+        if (!javadoc1) {
+            packageList = src;
+        }
     }
 
     public LinkArgument createLink() {
@@ -1389,22 +1400,62 @@ public class Javadoc extends Task {
         this.source = source;
     }
 
+    /**
+     * Adds a packageset.
+     *
+     * <p>All included directories will be translated into package
+     * names be converting the directory separator into dots.</p>
+     *
+     * @since 1.5
+     */
+    public void addPackageset(DirSet packageSet) {
+        packageSets.addElement(packageSet);
+    }
+
+    /**
+     * Adds a fileset.
+     *
+     * <p>All included files will be added as sourcefiles.  The task
+     * will automatically add
+     * <code>includes=&quot;**&#47;*.java&quot;</code> to the
+     * fileset.</p>
+     *
+     * @since 1.5
+     */
+    public void addFileset(FileSet fs) {
+        fs.createInclude().setName("**/*.java");
+        fileSets.addElement(fs);
+    }
+
     public void execute() throws BuildException {
         if ("javadoc2".equals(taskType)) {
             log("!! javadoc2 is deprecated. Use javadoc instead. !!");
         }
 
-        if (sourcePath == null) {
-            String msg = "sourcePath attribute must be set!";
+        Vector packagesToDoc = new Vector();
+        Path sourceDirs = new Path(getProject());
+        parsePackages(packagesToDoc, sourceDirs);
+
+        if (packagesToDoc.size() != 0 && sourceDirs.size() == 0) {
+            String msg = "sourcePath attribute must be set when "
+                + "specifying package names.";
             throw new BuildException(msg);
         }
 
+        Vector sourceFilesToDoc = (Vector) sourceFiles.clone();
+        addFileSets(sourceFilesToDoc);
+
+        if (packagesToDoc.size() == 0 && sourceFilesToDoc.size() == 0) {
+            throw new BuildException("No source files and no packages have "
+                                     + "been specified.");
+        }
+        
         log("Generating Javadoc", Project.MSG_INFO);
 
         Commandline toExecute = (Commandline) cmd.clone();
         toExecute.setExecutable(JavaEnvUtils.getJdkExecutable("javadoc"));
 
-// ------------------------------------------------ general javadoc arguments
+        // ------------------------------------------ general javadoc arguments
         if (doctitle != null) {
             toExecute.createArgument().setValue("-doctitle");
             toExecute.createArgument().setValue(expand(doctitle.getText()));
@@ -1431,14 +1482,14 @@ public class Javadoc extends Task {
         if (!javadoc1) {
             toExecute.createArgument().setValue("-classpath");
             toExecute.createArgument().setPath(classpath);
-            toExecute.createArgument().setValue("-sourcepath");
-            toExecute.createArgument().setPath(sourcePath);
+            if (sourceDirs.size() > 0) {
+                toExecute.createArgument().setValue("-sourcepath");
+                toExecute.createArgument().setPath(sourceDirs);
+            }
         } else {
+            sourceDirs.append(classpath);
             toExecute.createArgument().setValue("-classpath");
-            toExecute.createArgument()
-                .setValue(sourcePath.toString() 
-                          + System.getProperty("path.separator") 
-                          + classpath.toString());
+            toExecute.createArgument().setPath(sourceDirs);
         }
 
         if (version && doclet == null) {
@@ -1455,7 +1506,7 @@ public class Javadoc extends Task {
             }
         }
 
-// --------------------------------- javadoc2 arguments for default doclet
+        // ---------------------------- javadoc2 arguments for default doclet
 
         if (!javadoc1) {
             if (doclet != null) {
@@ -1616,71 +1667,53 @@ public class Javadoc extends Task {
 
         }
 
-        tmpList = null;
-        if (packageNames.size() > 0) {
-            Vector packages = new Vector();
-            Enumeration enum = packageNames.elements();
-            while (enum.hasMoreElements()) {
-                PackageName pn = (PackageName) enum.nextElement();
-                String name = pn.getName().trim();
-                if (name.endsWith(".*")) {
-                    packages.addElement(name);
-                } else {
-                    toExecute.createArgument().setValue(name);
-                }
-            }
+        File tmpList = null;
+        PrintWriter srcListWriter = null;
+        try {
 
-            Vector excludePackages = new Vector();
-            if (excludePackageNames.size() > 0) {
-                enum = excludePackageNames.elements();
-                while (enum.hasMoreElements()) {
-                    PackageName pn = (PackageName) enum.nextElement();
-                    excludePackages.addElement(pn.getName().trim());
+            /**
+             * Write sourcefiles and package names to a temporary file
+             * if requested.
+             */
+            if (useExternalFile) {
+                if (tmpList == null) {
+                    tmpList = fileUtils.createTempFile("javadoc", "", null);
+                    toExecute.createArgument()
+                        .setValue("@" + tmpList.getAbsolutePath());
                 }
+                srcListWriter = new PrintWriter(
+                                    new FileWriter(tmpList.getAbsolutePath(),
+                                                   true));
             }
-            if (packages.size() > 0) {
-                evaluatePackages(toExecute, sourcePath, packages, 
-                                 excludePackages);
-            }
-        }
 
-        if (sourceFiles.size() > 0) {
-            PrintWriter srcListWriter = null;
-            try {
-
-                /**
-                 * Write sourcefiles to a temporary file if requested.
-                 */
+            Enumeration enum = packagesToDoc.elements();
+            while (enum.hasMoreElements()) {
+                String packageName = (String) enum.nextElement();
                 if (useExternalFile) {
-                    if (tmpList == null) {
-                        tmpList = fileUtils.createTempFile("javadoc", "", null);
-                        toExecute.createArgument()
-                            .setValue("@" + tmpList.getAbsolutePath());
-                    }
-                    srcListWriter = new PrintWriter(
-                                        new FileWriter(tmpList
-                                                       .getAbsolutePath(),
-                                                       true));
+                    srcListWriter.println(packageName);
+                } else {
+                    toExecute.createArgument().setValue(packageName);
                 }
-
-                Enumeration enum = sourceFiles.elements();
-                while (enum.hasMoreElements()) {
-                    SourceFile sf = (SourceFile) enum.nextElement();
-                    String sourceFileName = sf.getFile().getAbsolutePath();
-                    if (useExternalFile) {
-                        srcListWriter.println(sourceFileName);
-                    } else {
-                        toExecute.createArgument().setValue(sourceFileName);
-                    }
+            }
+            
+            enum = sourceFilesToDoc.elements();
+            while (enum.hasMoreElements()) {
+                SourceFile sf = (SourceFile) enum.nextElement();
+                String sourceFileName = sf.getFile().getAbsolutePath();
+                if (useExternalFile) {
+                    srcListWriter.println(sourceFileName);
+                } else {
+                    toExecute.createArgument().setValue(sourceFileName);
                 }
+            }
 
-            } catch (IOException e) {
-                throw new BuildException("Error creating temporary file",
-                                         e, location);
-            } finally {
-                if (srcListWriter != null) {
-                    srcListWriter.close();
-                }
+        } catch (IOException e) {
+            tmpList.delete();
+            throw new BuildException("Error creating temporary file",
+                                     e, location);
+        } finally {
+            if (srcListWriter != null) {
+                srcListWriter.close();
             }
         }
 
@@ -1712,7 +1745,6 @@ public class Javadoc extends Task {
         } catch (IOException e) {
             throw new BuildException("Javadoc failed: " + e, e, location);
         } finally {
-
             if (tmpList != null) {
                 tmpList.delete();
                 tmpList = null;
@@ -1728,111 +1760,105 @@ public class Javadoc extends Task {
     }
 
     /**
-     * Given a source path, a list of package patterns, fill the given list
-     * with the packages found in that path subdirs matching one of the given
-     * patterns.
-     */
-    private void evaluatePackages(Commandline toExecute, Path sourcePath,
-                                  Vector packages, Vector excludePackages) {
-        log("Source path = " + sourcePath.toString(), Project.MSG_VERBOSE);
-        StringBuffer msg = new StringBuffer("Packages = ");
-        for (int i = 0; i < packages.size(); i++) {
-            if (i > 0) {
-                msg.append(",");
-            }
-            msg.append(packages.elementAt(i));
-        }
-        log(msg.toString(), Project.MSG_VERBOSE);
-
-        msg.setLength(0);
-        msg.append("Exclude Packages = ");
-        for (int i = 0; i < excludePackages.size(); i++) {
-            if (i > 0) {
-                msg.append(",");
+     * Add the files matched by the nested filesets to the Vector as
+     * SourceFile instances.
+     *
+     * @since 1.5
+     */
+    private void addFileSets(Vector sf) {
+        Enumeration enum = fileSets.elements();
+        while (enum.hasMoreElements()) {
+            FileSet fs = (FileSet) enum.nextElement();
+            File baseDir = fs.getDir(getProject());
+            DirectoryScanner ds = fs.getDirectoryScanner(getProject());
+            String[] files = ds.getIncludedFiles();
+            for (int i = 0; i < files.length; i++) {
+                sf.addElement(new SourceFile(new File(baseDir, files[i])));
             }
-            msg.append(excludePackages.elementAt(i));
         }
-        log(msg.toString(), Project.MSG_VERBOSE);
+    }
 
+    /**
+     * Add the directories matched by the nested dirsets to the Vector
+     * and the base directories of the dirsets to the Path.  It also
+     * handles the packages and excludepackages attributes and
+     * elements.
+     *
+     * @since 1.5
+     */
+    private void parsePackages(Vector pn, Path sp) {
         Vector addedPackages = new Vector();
-
-        String[] list = sourcePath.list();
-        if (list == null) {
-            list = new String[0];
-        }
-
-        FileSet fs = new FileSet();
-        fs.setDefaultexcludes(useDefaultExcludes);
-
-        Enumeration e = packages.elements();
-        while (e.hasMoreElements()) {
-            String pkg = (String) e.nextElement();
-            pkg = pkg.replace('.', '/');
-            if (pkg.endsWith("*")) {
-                pkg += "*";
+        Vector dirSets = (Vector) packageSets.clone();
+
+        // for each sourcePath entry, add a directoryset with includes
+        // taken from packagenames attribute and nested package
+        // elements and excludes taken from excludepackages attribute
+        // and nested excludepackage elements
+        if (sourcePath != null) {
+            PatternSet ps = new PatternSet();
+            Enumeration enum = packageNames.elements();
+            while (enum.hasMoreElements()) {
+                PackageName p = (PackageName) enum.nextElement();
+                String pkg = p.getName().replace('.', '/');
+                if (pkg.endsWith("*")) {
+                    pkg += "*";
+                }
+                ps.createInclude().setName(pkg);
             }
-
-            fs.createInclude().setName(pkg);
-        } // while
-
-        e = excludePackages.elements();
-        while (e.hasMoreElements()) {
-            String pkg = (String) e.nextElement();
-            pkg = pkg.replace('.', '/');
-            if (pkg.endsWith("*")) {
-                pkg += "*";
+            
+            enum = excludePackageNames.elements();
+            while (enum.hasMoreElements()) {
+                PackageName p = (PackageName) enum.nextElement();
+                String pkg = p.getName().replace('.', '/');
+                if (pkg.endsWith("*")) {
+                    pkg += "*";
+                }
+                ps.createExclude().setName(pkg);
             }
+            
 
-            fs.createExclude().setName(pkg);
-        }
-
-        PrintWriter packageListWriter = null;
-        try {
-            if (useExternalFile) {
-                tmpList = fileUtils.createTempFile("javadoc", "", null);
-                toExecute.createArgument()
-                    .setValue("@" + tmpList.getAbsolutePath());
-                packageListWriter = new PrintWriter(new FileWriter(tmpList));
+            String[] pathElements = sourcePath.list();
+            for (int i = 0; i < pathElements.length; i++) {
+                DirSet ds = new DirSet();
+                ds.setDefaultexcludes(useDefaultExcludes);
+                ds.setDir(new File(pathElements[i]));
+                ds.createPatternSet().addConfiguredPatternset(ps);
+                dirSets.addElement(ds);
             }
+        }
 
-            for (int j = 0; j < list.length; j++) {
-                File source = project.resolveFile(list[j]);
-                fs.setDir(source);
-
-                DirectoryScanner ds = fs.getDirectoryScanner(project);
-                String[] packageDirs = ds.getIncludedDirectories();
-
-                for (int i = 0; i < packageDirs.length; i++) {
-                    File pd = new File(source, packageDirs[i]);
-                    String[] files = pd.list(new FilenameFilter () {
-                            public boolean accept(File dir1, String name) {
-                                if (name.endsWith(".java")) {
-                                    return true;
-                                }
-                                return false;        // ignore dirs
-                            }
-                        });
-
-                    if (files.length > 0) {
-                        String pkgDir = 
-                            packageDirs[i].replace('/', '.').replace('\\', '.');
-                        if (!addedPackages.contains(pkgDir)) {
-                            if (useExternalFile) {
-                                packageListWriter.println(pkgDir);
-                            } else {
-                                toExecute.createArgument().setValue(pkgDir);
+        Enumeration enum = dirSets.elements();
+        while (enum.hasMoreElements()) {
+            DirSet ds = (DirSet) enum.nextElement();
+            File baseDir = ds.getDir(getProject());
+            log("scanning " + baseDir + " for packages.", Project.MSG_DEBUG); 
+            DirectoryScanner dsc = ds.getDirectoryScanner(getProject());
+            String[] dirs = dsc.getIncludedDirectories();
+            boolean containsPackages = false;
+            for (int i = 0; i < dirs.length; i++) {
+                // are there any java files in this directory?
+                File pd = new File(baseDir, dirs[i]);
+                String[] files = pd.list(new FilenameFilter () {
+                        public boolean accept(File dir1, String name) {
+                            if (name.endsWith(".java")) {
+                                return true;
                             }
-                            addedPackages.addElement(pkgDir);
+                            return false;        // ignore dirs
                         }
+                    });
+
+                if (files.length > 0) {
+                    containsPackages = true;
+                    String packageName = 
+                        dirs[i].replace(File.separatorChar, '.');
+                    if (!addedPackages.contains(packageName)) {
+                        addedPackages.addElement(packageName);
+                        pn.addElement(packageName);
                     }
                 }
             }
-        } catch (IOException ioex) {
-            throw new BuildException("Error creating temporary file",
-                                     ioex, location);
-        } finally {
-            if (packageListWriter != null) {
-                packageListWriter.close();
+            if (containsPackages) {
+                sp.createPathElement().setLocation(baseDir);
             }
         }
     }

src/main/org/apache/tools/ant/types/Path.java

@@ -356,7 +356,7 @@ public class Path extends DataType implements Cloneable {
 
         // empty path return empty string
         if (list.length == 0) {
-          return "";
+            return "";
         }
 
         // path containing one or more elements

xdocs/ant15_todo.xml

@@ -72,13 +72,6 @@
             <td>Steve + any other help he can get</td>
           </tr>
           
-          <tr>
-            <td>Make javadoc a real directory based task</td>
-            <td></td>
-            <td>Stefan, others welcome</td>
-          </tr>
-          
-
 <!-- for cut and paste use
           <tr>
             <td></td>
@@ -136,6 +129,11 @@
             <td></td>
             <td>Stefan</td>
           </tr>
+          <tr>
+            <td>Make javadoc a real directory based task</td>
+            <td></td>
+            <td>Stefan</td>
+          </tr>
         </table>
       </subsection>