You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@ant.apache.org by bo...@apache.org on 2018/09/28 18:42:32 UTC
[1/2] ant git commit: BZ 62424 minimal module support for javadoc
Repository: ant
Updated Branches:
refs/heads/master 24e47067a -> 872a9bcde
BZ 62424 minimal module support for javadoc
Project: http://git-wip-us.apache.org/repos/asf/ant/repo
Commit: http://git-wip-us.apache.org/repos/asf/ant/commit/048015b7
Tree: http://git-wip-us.apache.org/repos/asf/ant/tree/048015b7
Diff: http://git-wip-us.apache.org/repos/asf/ant/diff/048015b7
Branch: refs/heads/master
Commit: 048015b7d891edd74c8d458aa582a504511872c6
Parents: d100b90
Author: Stefan Bodewig <bo...@apache.org>
Authored: Fri Sep 28 20:27:53 2018 +0200
Committer: Stefan Bodewig <bo...@apache.org>
Committed: Fri Sep 28 20:27:53 2018 +0200
----------------------------------------------------------------------
WHATSNEW | 3 +
manual/Tasks/javadoc.html | 73 ++++++++--
.../org/apache/tools/ant/taskdefs/Javadoc.java | 142 ++++++++++++++++++-
3 files changed, 207 insertions(+), 11 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/ant/blob/048015b7/WHATSNEW
----------------------------------------------------------------------
diff --git a/WHATSNEW b/WHATSNEW
index 6cd11da..e5bfed3 100644
--- a/WHATSNEW
+++ b/WHATSNEW
@@ -32,6 +32,9 @@ Other changes:
command line arguments that are not supported explicitly by the
tasks via attributes.
+ * added several attributes to <javadoc> that support modules.
+ Bugzilla Report 62424
+
Changes from Ant 1.9.12 TO Ant 1.9.13
=====================================
http://git-wip-us.apache.org/repos/asf/ant/blob/048015b7/manual/Tasks/javadoc.html
----------------------------------------------------------------------
diff --git a/manual/Tasks/javadoc.html b/manual/Tasks/javadoc.html
index 430435f..a32ed47 100644
--- a/manual/Tasks/javadoc.html
+++ b/manual/Tasks/javadoc.html
@@ -92,9 +92,9 @@ to <javadoc> using <tt>classpath</tt>, <tt>classpathref</tt> attributes or
<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="3">At least one of the three or nested
- <code><sourcepath></code>, <code><fileset></code> or
- <code><packageset></code></td>
+ <td align="center" rowspan="3">At least one of the four or nested
+ <code><sourcepath></code>, <code><fileset></code>.
+ <code>module</code> or <code><packageset></code></td>
</tr>
<tr>
<td valign="top">sourcepathref</td>
@@ -109,6 +109,12 @@ to <javadoc> using <tt>classpath</tt>, <tt>classpathref</tt> attributes or
<td align="center" valign="top">all</td>
</tr>
<tr>
+ <td valign="top">modulenames</td>
+ <td valign="top">Comma separated list of module names -- see also
+ the nested <code>module</code> element. <em>since Ant 1.9.14</em></td>
+ <td align="center" valign="top">all</td>
+ </tr>
+ <tr>
<td valign="top">destdir</td>
<td valign="top">Destination directory for output files</td>
<td align="center" valign="top">all</td>
@@ -530,6 +536,36 @@ to <javadoc> using <tt>classpath</tt>, <tt>classpathref</tt> attributes or
<td align="center" valign="top">1.4</td>
<td align="center" valign="top">No</td>
</tr>
+ <tr>
+ <td valign="top">modulesourcepath</td>
+ <td valign="top">Specify where to find module source files
+ <em>since Ant 1.9.14</em></td>
+ <td align="center" valign="top">all</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">modulesourcepathref</td>
+ <td valign="top">Specify where to find module source files by <a
+ href="../using.html#references">reference</a> to a PATH defined elsewhere.
+ <em>since Ant 1.9.14</em></td>
+ <td align="center" valign="top">all</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">modulepath</td>
+ <td valign="top">Specify where to find module files
+ <em>since Ant 1.9.14</em></td>
+ <td align="center" valign="top">all</td>
+ <td align="center" valign="top">No</td>
+ </tr>
+ <tr>
+ <td valign="top">modulepathref</td>
+ <td valign="top">Specify where to find module files by <a
+ href="../using.html#references">reference</a> to a PATH defined elsewhere.
+ <em>since Ant 1.9.14</em></td>
+ <td align="center" valign="top">all</td>
+ <td align="center" valign="top">No</td>
+ </tr>
</table>
<h4><a name="groupattribute">Format of the group attribute</a></h4>
@@ -607,6 +643,24 @@ javadoc as source files.</p>
<h5>Parameters</h5>
Same as for <code>package</code>.
+<h4>module</h4>
+<p><em>since Ant 1.9.14</em></p>
+<p>Same as one entry in the list given by <code>modulenames</code>.</p>
+
+<h5>Parameters</h5>
+<table width="90%" 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 module name</td>
+ <td align="center" valign="top">Yes</td>
+ </tr>
+</table>
+
<h4>source</h4>
<p>Same as one entry in the list given by <code>sourcefiles</code>.</p>
@@ -830,12 +884,13 @@ the javadoc program.
</tr>
</table>
-<h4>sourcepath, classpath and bootclasspath</h4>
-<p><code>Javadoc</code>'s <i>sourcepath</i>, <i>classpath</i> and
-<i>bootclasspath</i> attributes are <a href="../using.html#path">PATH like
-structure</a> and can also be set via nested <i>sourcepath</i>,
-<i>classpath</i> and <i>bootclasspath</i> elements
-respectively.</p>
+<h4>sourcepath, classpath, bootclasspath, modulepath, modulesourcepath</h4>
+<p><code>Javadoc</code>'s <i>sourcepath</i>, <i>classpath</i>,
+<i>bootclasspath</i>, <i>modulepath</i>, and <i>modulesourcepath</i>
+attributes are <a href="../using.html#path">PATH like structure</a>
+and can also be set via nested <i>sourcepath</i>,
+<i>classpath</i>, <i>bootclasspath</i>, <i>modulepath</i>,
+and <i>modulesourcepath</i> elements respectively.</p>
<h4>arg</h4>
http://git-wip-us.apache.org/repos/asf/ant/blob/048015b7/src/main/org/apache/tools/ant/taskdefs/Javadoc.java
----------------------------------------------------------------------
diff --git a/src/main/org/apache/tools/ant/taskdefs/Javadoc.java b/src/main/org/apache/tools/ant/taskdefs/Javadoc.java
index 7a5c2ec..999b103 100644
--- a/src/main/org/apache/tools/ant/taskdefs/Javadoc.java
+++ b/src/main/org/apache/tools/ant/taskdefs/Javadoc.java
@@ -37,6 +37,7 @@ import java.util.Collections;
import java.util.Enumeration;
import java.util.HashSet;
import java.util.Iterator;
+import java.util.List;
import java.util.Locale;
import java.util.StringTokenizer;
import java.util.Vector;
@@ -447,11 +448,14 @@ public class Javadoc extends Task {
private final Vector<SourceFile> sourceFiles = new Vector<SourceFile>();
private final Vector<PackageName> packageNames = new Vector<PackageName>();
private final Vector<PackageName> excludePackageNames = new Vector<PackageName>(1);
+ private final List<PackageName> moduleNames = new ArrayList<PackageName>();
private boolean author = true;
private boolean version = true;
private DocletInfo doclet = null;
private Path classpath = null;
private Path bootclasspath = null;
+ private Path modulePath = null;
+ private Path moduleSourcePath = null;
private String group = null;
private String packageList = null;
private final Vector<LinkArgument> links = new Vector<LinkArgument>();
@@ -563,6 +567,88 @@ public class Javadoc extends Task {
}
/**
+ * Specify where to find modules
+ *
+ * @param src a Path instance containing the modules.
+ *
+ * @since Ant 1.9.14
+ */
+ public void setModulePath(final Path mp) {
+ if (modulePath == null) {
+ modulePath = mp;
+ } else {
+ modulePath.append(mp);
+ }
+ }
+
+ /**
+ * Create a path to be configured with the locations of the module
+ * files.
+ *
+ * @return a new Path instance to be configured by the Ant core.
+ *
+ * @since Ant 1.9.14
+ */
+ public Path createModulePath() {
+ if (modulePath == null) {
+ modulePath = new Path(getProject());
+ }
+ return modulePath.createPath();
+ }
+
+ /**
+ * Adds a reference to a path defined elsewhere that defines the module path.
+ *
+ * @param r the reference containing the module path definition.
+ *
+ * @since Ant 1.9.14
+ */
+ public void setModulePathref(final Reference r) {
+ createModulePath().setRefid(r);
+ }
+
+ /**
+ * Specify where to find sources for modules
+ *
+ * @param src a Path instance containing the sources for modules.
+ *
+ * @since Ant 1.9.14
+ */
+ public void setModuleSourcePath(final Path mp) {
+ if (moduleSourcePath == null) {
+ moduleSourcePath = mp;
+ } else {
+ moduleSourcePath.append(mp);
+ }
+ }
+
+ /**
+ * Create a path to be configured with the locations of the module
+ * source files.
+ *
+ * @return a new Path instance to be configured by the Ant core.
+ *
+ * @since Ant 1.9.14
+ */
+ public Path createModuleSourcePath() {
+ if (moduleSourcePath == null) {
+ moduleSourcePath = new Path(getProject());
+ }
+ return moduleSourcePath.createPath();
+ }
+
+ /**
+ * Adds a reference to a path defined elsewhere that defines the module source path.
+ *
+ * @param r the reference containing the module source path definition.
+ *
+ * @since Ant 1.9.14
+ */
+ public void setModuleSourcePathref(final Reference r) {
+ createModuleSourcePath().setRefid(r);
+ }
+
+ /**
* Set the directory where the Javadoc output will be generated.
*
* @param dir the destination directory.
@@ -616,6 +702,23 @@ public class Javadoc extends Task {
}
/**
+ * Set the module names to be processed.
+ *
+ * @param modules a comma separated list of module names
+ *
+ * @since Ant 1.9.14
+ */
+ public void setModulenames(final String modules) {
+ final StringTokenizer tok = new StringTokenizer(modules, ",");
+ while (tok.hasMoreTokens()) {
+ final String m = tok.nextToken();
+ final PackageName mn = new PackageName();
+ mn.setName(m);
+ addModule(mn);
+ }
+ }
+
+ /**
* Add a single package to be processed.
*
* If the package name ends with ".*" the Javadoc task
@@ -628,6 +731,17 @@ public class Javadoc extends Task {
}
/**
+ * Add a single module to be processed.
+ *
+ * @param mn the module name
+ *
+ * @since Ant 1.9.14
+ */
+ public void addModule(final PackageName mn) {
+ moduleNames.add(mn);
+ }
+
+ /**
* Set the list of packages to be excluded.
*
* @param packages a comma separated list of packages to be excluded.
@@ -1746,6 +1860,7 @@ public class Javadoc extends Task {
doGroup(toExecute); // group attribute
doGroups(toExecute); // groups attribute
doDocFilesSubDirs(toExecute); // docfilessubdir attribute
+ doModuleArguments(toExecute);
doJava14(toExecute);
if (breakiterator && (doclet == null || JAVADOC_5)) {
@@ -1862,8 +1977,8 @@ public class Javadoc extends Task {
private void checkPackagesToDoc(
final Vector<String> packagesToDoc, final Vector<SourceFile> sourceFilesToDoc) {
if (packageList == null && packagesToDoc.size() == 0
- && sourceFilesToDoc.size() == 0) {
- throw new BuildException("No source files and no packages have "
+ && sourceFilesToDoc.size() == 0 && moduleNames.isEmpty()) {
+ throw new BuildException("No source files, no packages and no modules have "
+ "been specified.");
}
}
@@ -2549,6 +2664,29 @@ public class Javadoc extends Task {
return fileContents;
}
+ private void doModuleArguments(Commandline toExecute) {
+ if (!moduleNames.isEmpty()) {
+ StringBuilder sb = null;
+ for (PackageName mn : moduleNames) {
+ if (sb == null) {
+ sb = new StringBuilder(mn.getName());
+ } else {
+ sb.append(",").append(mn.getName());
+ }
+ }
+ toExecute.createArgument().setValue("--module");
+ toExecute.createArgument().setValue(sb.toString());
+ }
+ if (modulePath != null) {
+ toExecute.createArgument().setValue("--module-path");
+ toExecute.createArgument().setPath(modulePath);
+ }
+ if (moduleSourcePath != null) {
+ toExecute.createArgument().setValue("--module-source-path");
+ toExecute.createArgument().setPath(moduleSourcePath);
+ }
+ }
+
private class JavadocOutputStream extends LogOutputStream {
JavadocOutputStream(final int level) {
super(Javadoc.this, level);
[2/2] ant git commit: Merge branch '1.9.x'
Posted by bo...@apache.org.
Merge branch '1.9.x'
Project: http://git-wip-us.apache.org/repos/asf/ant/repo
Commit: http://git-wip-us.apache.org/repos/asf/ant/commit/872a9bcd
Tree: http://git-wip-us.apache.org/repos/asf/ant/tree/872a9bcd
Diff: http://git-wip-us.apache.org/repos/asf/ant/diff/872a9bcd
Branch: refs/heads/master
Commit: 872a9bcdedc9611e3703cfe739dc53896adce4ee
Parents: 24e4706 048015b
Author: Stefan Bodewig <bo...@apache.org>
Authored: Fri Sep 28 20:42:18 2018 +0200
Committer: Stefan Bodewig <bo...@apache.org>
Committed: Fri Sep 28 20:42:18 2018 +0200
----------------------------------------------------------------------
WHATSNEW | 3 +
manual/Tasks/javadoc.html | 71 +++++++++-
.../org/apache/tools/ant/taskdefs/Javadoc.java | 135 ++++++++++++++++++-
3 files changed, 199 insertions(+), 10 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/ant/blob/872a9bcd/WHATSNEW
----------------------------------------------------------------------
diff --cc WHATSNEW
index 19b2c0f,e5bfed3..a773da1
--- a/WHATSNEW
+++ b/WHATSNEW
@@@ -46,7 -32,10 +46,10 @@@ Other changes
command line arguments that are not supported explicitly by the
tasks via attributes.
+ * added several attributes to <javadoc> that support modules.
+ Bugzilla Report 62424
+
-Changes from Ant 1.9.12 TO Ant 1.9.13
+Changes from Ant 1.10.4 TO Ant 1.10.5
=====================================
Fixed bugs:
http://git-wip-us.apache.org/repos/asf/ant/blob/872a9bcd/manual/Tasks/javadoc.html
----------------------------------------------------------------------
diff --cc manual/Tasks/javadoc.html
index eaebb4e,a32ed47..c818e92
--- a/manual/Tasks/javadoc.html
+++ b/manual/Tasks/javadoc.html
@@@ -24,492 -24,560 +24,529 @@@
<body>
-<h2><a name="javadoc">Javadoc/<i>Javadoc2</i></a></h2>
+<h2 id="javadoc">Javadoc/<em>Javadoc2</em></h2>
+<p><em><u>Deprecation</u>: the <code>javadoc2</code> task simply points to the <code>javadoc</code>
+task and it's there for backwards compatibility reasons. Since this task will be removed in future
+versions, you are strongly encouraged to use <a href="javadoc.html">javadoc</a> instead.</em></p>
<h3>Description</h3>
-<p>Generates code documentation using the javadoc tool.</p>
-<p>The source directory will be recursively scanned for Java source files to process
-but only those matching the inclusion rules, and not matching the exclusions rules
-will be passed to the javadoc tool. This
-allows wildcards to be used to choose between package names, reducing verbosity
-and management costs over time. This task, however, has no notion of
-"changed" 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>NOTE: since javadoc calls System.exit(), javadoc cannot be run inside the
-same VM as Apache 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 <code>build.xml</code> 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
-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.2 means available if your current Java VM is
-a 1.2 VM (but not 1.3 or later), 1.4+ for any VM of at least version 1.4, otherwise
-any VM of at least version 1.2 is acceptable. JDKs <1.4 are no longer supported.
-If you specify the <code>executable</code> attribute it is up to you
-to ensure that this command supports the attributes you wish to use.</p>
-
-<p><b>Note:</b><br>When generating the JavaDocs for classes which contains annotations
-you maybe get a <tt>java.lang.ClassCastException: com.sun.tools.javadoc.ClassDocImpl</tt>.
-This is due <a href="https://bugs.openjdk.java.net/browse/JDK-6442982" target="_blank">bug-6442982</a>. The cause is that JavaDoc cannot find the implementations of used annotations.
-The workaround is providing the jars with these implementations (like JAXBs <tt>@XmlType</tt>, ...)
-to <javadoc> using <tt>classpath</tt>, <tt>classpathref</tt> attributes or nested
-<classpath> element.</p>
-
-<p><b>Note:</b> many problems with running javadoc stem from command
- lines that have become too long - even though the error message
- doesn't give the slightest hint this may be the problem. If you
- encounter problems with the task, try to set
- the <code>useexternalfile</code> attribute to <code>true</code>
- first.</p>
-
-<p>If you use multiple ways to specify where javadoc should be looking
- for sources your result will be the union of all specified
- documentations. If you, e.g., specify a sourcepath attribute and
- also a nested packageset both pointing at the same directory your
- excludepackagenames attribute won't have any effect unless it agrees
- with the exclude patterns of the packageset (and vice versa).</p>
+<p>Generates code documentation using the <kbd>javadoc</kbd> tool.</p>
+<p>The source directory will be recursively scanned for Java source files to process but only those
+matching the inclusion rules, and not matching the exclusions rules will be passed to
+the <kbd>javadoc</kbd> tool. This allows wildcards to be used to choose between package names,
+reducing verbosity and management costs over time. This task, however, has no notion of
+"changed" 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><strong>Note</strong>: since <kbd>javadoc</kbd>
+calls <code class="code">System.exit()</code>, <kbd>javadoc</kbd> cannot be run inside the same
+JVM as Apache Ant without breaking functionality. For this reason, this task always forks JVM. This
+overhead is not significant since <kbd>javadoc</kbd> is normally a heavy application and will be
+called infrequently.</p>
+<p><strong>Note</strong>: the <var>packagelist</var> 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 <code>build.xml</code> file. This option was added in order to make it easier to migrate
+from regular makefiles, where you would use this option of <kbd>javadoc</kbd>. The packages
+listed in <var>packagelist</var> 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>In the table below, 1.2 means available if your current JVM is exactly of version 1.2 (not 1.3 or
+later), 1.4+ for any JVM of at least version 1.4, otherwise any JVM of at least version 1.2 is
+acceptable. <em>JDKs prior to 1.4 are no longer supported.</em> If you specify
+the <var>executable</var> attribute it is up to you to ensure that this command supports the
+attributes you wish to use.</p>
+
+<p><strong>Note</strong>: When generating the JavaDocs for classes which contains annotations you
+maybe get a <code class="output">java.lang.ClassCastException:
+com.sun.tools.javadoc.ClassDocImpl</code>. This is
+due <a href="https://bugs.openjdk.java.net/browse/JDK-6442982" target="_top">bug 6442982</a>. The
+cause is that <kbd>javadoc</kbd> cannot find the implementations of used annotations. The
+workaround is providing the jars with these implementations (like
+JAXBs <code class="code">@XmlType</code>, ...) to <code><javadoc></code>
+using <var>classpath</var>, <var>classpathref</var> attributes or
+nested <code><classpath></code> element.</p>
+
+<p><strong>Note</strong>: many problems with running <kbd>javadoc</kbd> stem from command lines
+that have become too long—even though the error message doesn't give the slightest hint this
+may be the problem. If you encounter problems with the task, try to set
+the <var>useexternalfile</var> attribute to <q>true</q> first.</p>
+
+<p>If you use multiple ways to specify where <kbd>javadoc</kbd> should be looking for sources, your
+result will be the union of all specified documentations. If you, e.g., specify
+a <var>sourcepath</var> attribute and also a nested <code>packageset</code> both pointing at the
+same directory your <var>excludepackagenames</var> attribute won't have any effect unless it agrees
+with the <var>exclude</var> patterns of the <code>packageset</code> (and vice versa).</p>
<h3>Parameters</h3>
-<table border="1" cellpadding="2" cellspacing="0">
+<table class="attr">
<tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Availability on Java</b></td>
- <td align="center" valign="top"><b>Required</b></td>
+ <th scope="col">Attribute</th>
+ <th scope="col">Description</th>
+ <th scope="col">Availability on Java</th>
+ <th scope="col">Required</th>
</tr>
<tr>
- <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="3">At least one of the four or nested
- <code><sourcepath></code>, <code><fileset></code>.
+ <td>sourcepath</td>
+ <td>Specify where to find source files</td>
+ <td>all</td>
- <td rowspan="3">At least one of the three or
- nested <code><sourcepath></code>, <code><fileset></code>
++ <td rowspan="4">At least one of the three or
++ nested <code><sourcepath></code>, <code><fileset></code>,
+ <code>module</code> or <code><packageset></code></td>
+ or <code><packageset></code></td>
</tr>
<tr>
- <td valign="top">sourcepathref</td>
- <td valign="top">Specify where to find source files by <a
- href="../using.html#references">reference</a> to a PATH defined elsewhere.</td>
- <td align="center" valign="top">all</td>
+ <td>sourcepathref</td>
+ <td>Specify where to find source files by <a href="../using.html#references">reference</a> to a
+ <var>sourcepath</var> defined elsewhere.</td>
+ <td class="left">all</td>
</tr>
<tr>
- <td valign="top">sourcefiles</td>
- <td valign="top">Comma separated list of source files -- see also
- the nested <code>source</code> element.</td>
- <td align="center" valign="top">all</td>
+ <td>sourcefiles</td>
+ <td>Comma separated list of source files—see also the nested <code>source</code>
+ element.</td>
+ <td class="left">all</td>
</tr>
<tr>
- <td valign="top">modulenames</td>
- <td valign="top">Comma separated list of module names -- see also
- the nested <code>module</code> element. <em>since Ant 1.9.14</em></td>
- <td align="center" valign="top">all</td>
++ <td>modulenames</td>
++ <td>Comma separated list of module names -- see also
++ the nested <code>module</code> element. <em>since Ant 1.10.6</em></td>
++ <td>all</td>
+ </tr>
+ <tr>
- <td valign="top">destdir</td>
- <td valign="top">Destination directory for output files</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">Yes, unless a doclet has been specified.</td>
+ <td>destdir</td>
+ <td>Destination directory for output files</td>
+ <td>all</td>
+ <td>Yes, unless a <var>doclet</var> has been specified.</td>
</tr>
<tr>
- <td valign="top">maxmemory</td>
- <td valign="top">Max amount of memory to allocate to the javadoc VM</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>maxmemory</td>
+ <td>Max amount of memory to allocate to the <kbd>javadoc</kbd> JVM</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">packagenames</td>
- <td valign="top">Comma separated list of package files (with terminating
- wildcard) -- see also the nested <code>package</code> element.</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>packagenames</td>
+ <td>Comma separated list of package files (with terminating wildcard)—see also the
+ nested <code>package</code> element.</td>
+ <td>all</td>
+ <td>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">No</td>
+ <td>packageList</td>
+ <td>The name of a file containing the packages to process</td>
+ <td>all</td>
+ <td>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>
- <td align="center" valign="top">No</td>
+ <td>classpath</td>
+ <td>Specify where to find user class files</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <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">all</td>
- <td align="center" valign="top">No</td>
+ <td>Bootclasspath</td>
+ <td>Override location of class files loaded by the bootstrap class loader</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">classpathref</td>
- <td valign="top">Specify where to find user class files by <a
- href="../using.html#references">reference</a> to a PATH defined elsewhere.</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>classpathref</td>
+ <td>Specify where to find user class files by <a href="../using.html#references">reference</a>
+ to a <var>classpath</var> defined elsewhere.</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">bootclasspathref</td>
- <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">all</td>
- <td align="center" valign="top">No</td>
+ <td>bootclasspathref</td>
+ <td>Override location of class files loaded by the bootstrap class loader
+ by <a href="../using.html#references">reference</a> to a <var>bootclasspath</var> defined
+ elsewhere.</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">Extdirs</td>
- <td valign="top">Override location of installed extensions</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>Extdirs</td>
+ <td>Override location of installed extensions</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">Overview</td>
- <td valign="top">Read overview documentation from HTML file</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>Overview</td>
+ <td>Read overview documentation from HTML file</td>
+ <td>all</td>
+ <td>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>
+ <td>access</td>
+ <td>Access mode: one of <q>public</q>, <q>protected</q>, <q>package</q>, or <q>private</q></td>
+ <td>all</td>
+ <td>No; default is <q>protected</q></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>
- <td align="center" valign="top">No</td>
+ <td>Public</td>
+ <td>Show only public classes and members</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">Protected</td>
- <td valign="top">Show protected/public classes and members (default)</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>Protected</td>
+ <td>Show protected/public classes and members (default)</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">Package</td>
- <td valign="top">Show package/protected/public classes and members</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>Package</td>
+ <td>Show package/protected/public classes and members</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">Private</td>
- <td valign="top">Show all classes and members</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>Private</td>
+ <td>Show all classes and members</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">Old</td>
- <td valign="top">Generate output using JDK 1.1 emulating
- doclet.<br>
- <b>Note:</b> as of Ant 1.8.0 this attribute doesn't have any
- effect since the javadoc of Java 1.4 (required by Ant 1.8.0)
- doesn't support the -1.1 switch anymore.</td>
- <td align="center" valign="top">1.2</td>
- <td align="center" valign="top">No</td>
+ <td>Old</td>
+ <td>Generate output using JDK 1.1 emulating doclet.<br/><strong>Note</strong>: <em>Since Ant
+ 1.8.0</em> this attribute has no effect because <kbd>javadoc</kbd> of Java 1.4 and later
+ does not support the <kbd>-1.1</kbd> switch anymore.</td>
+ <td>1.2</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">Verbose</td>
- <td valign="top">Output messages about what Javadoc is doing</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>Verbose</td>
+ <td>Output messages about what <kbd>javadoc</kbd> is doing</td>
+ <td>all</td>
+ <td>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">all</td>
- <td align="center" valign="top">No</td>
+ <td>Locale</td>
+ <td>Locale to be used, e.g. <q>en_US</q> or <q>en_US_WIN</q></td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">Encoding</td>
- <td valign="top">Source file encoding name</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>Encoding</td>
+ <td>Source file encoding name</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">Version</td>
- <td valign="top">Include @version paragraphs</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>Version</td>
+ <td>Include <code>@version</code> paragraphs</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">Use</td>
- <td valign="top">Create class and package usage pages</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>Use</td>
+ <td>Create class and package usage pages</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">Author</td>
- <td valign="top">Include @author paragraphs</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>Author</td>
+ <td>Include <code>@author</code> paragraphs</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">Splitindex</td>
- <td valign="top">Split index into one file per letter</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>Splitindex</td>
+ <td>Split index into one file per letter</td>
+ <td>all</td>
+ <td>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">all</td>
- <td align="center" valign="top">No</td>
+ <td>Windowtitle</td>
+ <td>Browser window title for the documentation (text)</td>
+ <td>all</td>
+ <td>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">all</td>
- <td align="center" valign="top">No</td>
+ <td>Doctitle</td>
+ <td>Include title for the package index (first) page (HTML code)</td>
+ <td>all</td>
+ <td>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">all</td>
- <td align="center" valign="top">No</td>
+ <td>Header</td>
+ <td>Include header text for each page (HTML code)</td>
+ <td>all</td>
+ <td>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">all</td>
- <td align="center" valign="top">No</td>
+ <td>Footer</td>
+ <td>Include footer text for each page (HTML code)</td>
+ <td>all</td>
+ <td>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">all</td>
- <td align="center" valign="top">No</td>
+ <td>bottom</td>
+ <td>Include bottom text for each page (HTML code)</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">link</td>
- <td valign="top">Create links to javadoc output at the given URL
- -- see also the nested <code>link</code> element.</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>link</td>
+ <td>Create links to <code>javadoc</code> output at the given URL—see also the
+ nested <code>link</code> element.</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">linkoffline</td>
- <td valign="top">Link to docs at <code><url></code> using package list at
- <code><url2></code> - separate the URLs by using a space character -- see
- also the nested <code>link</code> element.</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>linkoffline</td>
+ <td>Link to docs at <samp><em>url</em></samp> using package list
+ at <samp><em>alt-url</em></samp> by specifying a
+ value <q><em>url</em> <em>alt-url</em></q> (space as separator). A shorthand for the
+ nested <code>link</code> element with <var>offline</var>=<q>true</q>.</td>
+ <td>all</td>
+ <td>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> -- see also the nested
- <code>group</code> element.</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>group</td>
+ <td>Group specified packages together in overview page. The format is as
+ described <a href="#groupattribute">below</a>—see also the nested <code>group</code>
+ element.</td>
+ <td>all</td>
+ <td>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>
- <td align="center" valign="top">No</td>
+ <td>nodeprecated</td>
+ <td>Do not include <code>@deprecated</code> information</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">nodeprecatedlist</td>
- <td valign="top">Do not generate deprecated list</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>nodeprecatedlist</td>
+ <td>Do not generate deprecated list</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">notree</td>
- <td valign="top">Do not generate class hierarchy</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>notree</td>
+ <td>Do not generate class hierarchy</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">noindex</td>
- <td valign="top">Do not generate index</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>noindex</td>
+ <td>Do not generate index</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">nohelp</td>
- <td valign="top">Do not generate help link</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>nohelp</td>
+ <td>Do not generate help link</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">nonavbar</td>
- <td valign="top">Do not generate navigation bar</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>nonavbar</td>
+ <td>Do not generate navigation bar</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">serialwarn</td>
- <td valign="top">Generate warning about @serial tag</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>serialwarn</td>
+ <td>Generate warning about <code>@serial</code> tag</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">helpfile</td>
- <td valign="top">Specifies the HTML help file to use</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>helpfile</td>
+ <td>Specifies the HTML help file to use</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">stylesheetfile</td>
- <td valign="top">Specifies the CSS stylesheet to use</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>stylesheetfile</td>
+ <td>Specifies the CSS stylesheet to use</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">charset</td>
- <td valign="top">Charset for cross-platform viewing of generated
- documentation</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>charset</td>
+ <td>Charset for cross-platform viewing of generated documentation</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">docencoding</td>
- <td valign="top">Output file encoding name</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
- </tr>
+ <td>docencoding</td>
+ <td>Output file encoding name</td>
+ <td>all</td>
+ <td>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 -- see also the nested
- <code>doclet</code> element.</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
- </tr>
+ <td>doclet</td>
+ <td>Specifies the class file that starts the doclet used in generating the
+ documentation—see also the nested <code>doclet</code> element.</td>
+ <td>all</td>
+ <td>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">all</td>
- <td align="center" valign="top">No</td>
+ <td>docletpath</td>
+ <td>Specifies the path to the doclet class file that is specified with the <kbd>-doclet</kbd>
+ option.</td>
+ <td>all</td>
+ <td>No</td>
</tr>
- <tr>
- <td valign="top">docletpathref</td>
- <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">all</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">additionalparam</td>
- <td valign="top">Lets you add additional parameters to the javadoc
- command line. Useful for doclets. Parameters containing spaces
- need to be quoted using &quot; -- see also the nested
- <code>arg</code> element.</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <tr>
+ <td>docletpathref</td>
+ <td>Specifies the path to the doclet class file that is specified with the <kbd>-doclet</kbd>
+ option by <a href="../using.html#references">reference</a> to a path defined elsewhere.</td>
+ <td>all</td>
+ <td>No</td>
</tr>
<tr>
- <td valign="top">failonerror</td>
- <td valign="top">Stop the buildprocess if the command exits with a
- returncode other than 0.</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <td>additionalparam</td>
+ <td>Lets you add additional parameters to the <kbd>javadoc</kbd> command line. Useful for
+ doclets. Parameters containing spaces need to be quoted using &quot;—see also the
+ nested <code>arg</code> element.</td>
+ <td>all</td>
+ <td>No</td>
</tr>
- <tr>
- <td valign="top">failonwarning</td>
- <td valign="top">Stop the buildprocess if a warning is emitted -
- i.e. if javadoc's output contains the word "warning". <em>since
- Ant 1.9.4</em></td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
+ <tr>
+ <td>failonerror</td>
+ <td>Stop the build process if the command exits with a return code other than <q>0</q>.</td>
+ <td>all</td>
+ <td>No</td>
</tr>
- <tr>
- <td valign="top">excludepackagenames</td>
- <td valign="top">comma separated list of packages you don't want
- docs for -- see also the nested <code>excludepackage</code> element.</td>
- <td align="center" valign="top">all</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">defaultexcludes</td>
- <td valign="top">indicates whether default excludes should be used
- (<code>yes</code> | <code>no</code>); default excludes are used when omitted.</td>
- <td align="center" valign="top">all</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">useexternalfile</td>
- <td valign="top">indicates whether the sourcefile name specified
- in srcfiles or as nested source elements should be written to a
- temporary file to make the command line shorter. Also applies to
- the package names specified via the packagenames attribute or
- nested package elements. <em>Since Ant 1.7.0</em>, also applies
- to all the other command line options.
- (<code>yes</code> | <code>no</code>). Default is no.</td>
- <td align="center" valign="top">all</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">source</td>
- <td valign="top">Necessary to enable javadoc to handle assertions
- present in J2SE v 1.4 source code. Set this to "1.4" to
- documents code that compiles using <code>"javac -source
- 1.4"</code>.<br>
- A default value for this attribute can be provided using the magic
- <a
- href="../javacprops.html#source"><code>ant.build.javac.source</code></a>
- property.</td>
- <td align="center" valign="top">1.4+</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">linksource</td>
- <td valign="top">Generate hyperlinks to source files.
- <em>since Ant 1.6</em>.
- (<code>yes</code> | <code>no</code>). Default is no.</td>
- <td align="center" valign="top">1.4+</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">breakiterator</td>
- <td valign="top">Use the new breakiterator algorithm.
- <em>since Ant 1.6</em>.
- (<code>yes</code> | <code>no</code>). Default is no.</td>
- <td align="center" valign="top">1.4+</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">noqualifier</td>
- <td valign="top">Enables the <code>-noqualifier</code> argument -
- must be <code>all</code> or a colon separated list of packages.
- <em>since Ant 1.6</em>.</td>
- <td align="center" valign="top">1.4+</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">includenosourcepackages</td>
- <td valign="top">If set to true, packages that don't contain Java
- source but a package.html will get documented as well.
- <em>since Ant 1.6.3</em>.</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No (default is <code>false</code>)</td>
- </tr>
- <tr>
- <td valign="top">executable</td>
- <td valign="top">Specify a particular <code>javadoc</code> executable
- to use in place of the default binary (found in the same JDK as Ant is running in).
- <em>since Ant 1.6.3</em>.</td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">docfilessubdirs</td>
- <td valign="top">Enables deep-copying of <code>doc-files</code>
- subdirectories. Defaults to false. <em>since Ant 1.8.0</em>.</td>
- <td align="center" valign="top">1.4</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">excludedocfilessubdir</td>
- <td valign="top">Colon-separated list of <code>doc-files</code>'
- subdirectories to exclude if <code>docfilessubdirs</code> is
- true. <em>since Ant 1.8.0</em>.</td>
- <td align="center" valign="top">1.4</td>
- <td align="center" valign="top">No</td>
- </tr>
- <tr>
- <td valign="top">postProcessGeneratedJavadocs</td>
- <td valign="top">Whether to post-process the generated javadocs in
- order to mitigate CVE-2013-1571. Defaults to true. <em>Since Ant
- 1.9.2</em><br>
- There is a frame injection attack possible in javadocs generated by Oracle
- JDKs prior to Java7 Update 25 (<a href="http://www.oracle.com/technetwork/java/javase/7u25-relnotes-1955741.html#jpi-upt" target="_blank">details</a>).
- When this flag is set to true, Ant will check whether the docs are vulnerable
- and will try to fix them.
- </td>
- <td align="center" valign="top">1.4</td>
- <td align="center" valign="top">No</td>
+ <tr>
+ <td>failonwarning</td>
+ <td>Stop the build process if a warning is emitted—i.e. if <kbd>javadoc</kbd>'s output
+ contains the word <q>warning</q>. <em>since Ant 1.9.4</em></td>
+ <td>all</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>excludepackagenames</td>
+ <td>comma separated list of packages you don't want docs for—see also the
+ nested <code>excludepackage</code> element.</td>
+ <td>all</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>defaultexcludes</td>
+ <td>indicates whether default excludes should be used (<q>yes|no</q>).</td>
+ <td>all</td>
+ <td>No; defaults to <q>yes</q></td>
+ </tr>
+ <tr>
+ <td>useexternalfile</td>
+ <td>indicates whether the source file names specified in <var>srcfiles</var> or as
+ nested <code>source</code> elements should be written to a temporary file to make the command
+ line shorter. Also applies to the package names specified via the <var>packagenames</var>
+ attribute or nested <code>package</code> elements. <em>Since Ant 1.7.0</em>, also applies to
+ all the other command line options. (<q>yes|no</q>).</td>
+ <td>all</td>
+ <td>No; default is <q>no</q></td>
+ </tr>
+ <tr>
+ <td>source</td>
+ <td>Enable <kbd>javadoc</kbd> to handle Java language features. Set this to <q>1.4</q> to
+ document code that compiles using <kbd>javac -source 1.4</kbd>, etc.</td>
+ <td>1.4+</td>
+ <td>No; default can be provided using the magic
+ <a href="../javacprops.html#source"><code>ant.build.javac.source</code></a> property.</td>
+ </tr>
+ <tr>
+ <td>linksource</td>
+ <td>Generate hyperlinks to source files. <em>since Ant 1.6</em>. (<q>yes|no</q>).</td>
+ <td>1.4+</td>
+ <td>No; default is <q>no</q></td>
+ </tr>
+ <tr>
+ <td>breakiterator</td>
+ <td>Use the new break iterator algorithm. <em>since Ant 1.6</em>. (<q>yes|no</q>).</td>
+ <td>1.4+</td>
+ <td>No; default is <q>no</q></td>
+ </tr>
+ <tr>
+ <td>noqualifier</td>
+ <td>Enables the <kbd>-noqualifier</kbd> argument—must be <q>all</q> or a colon separated
+ list of packages. <em>since Ant 1.6</em>.</td>
+ <td>1.4+</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>includenosourcepackages</td>
+ <td>If set to <q>true</q>, packages that don't contain Java source but
+ a <samp>package.html</samp> will get documented as well. <em>since Ant 1.6.3</em>.</td>
+ <td>all</td>
+ <td>No; default is <q>false</q></td>
+ </tr>
+ <tr>
+ <td>executable</td>
+ <td>Specify a particular <kbd>javadoc</kbd> executable to use in place of the default binary
+ (found in the same JDK as Ant is running in). <em>since Ant 1.6.3</em>.</td>
+ <td>all</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>docfilessubdirs</td>
+ <td>Enables deep-copying of <samp>doc-files</samp> subdirectories. <em>since Ant
+ 1.8.0</em>.</td>
+ <td>1.4</td>
+ <td>No; defaults to <q>false</q></td>
+ </tr>
+ <tr>
+ <td>excludedocfilessubdir</td>
+ <td>Colon-separated list of <samp>doc-files</samp> subdirectories to exclude
+ if <var>docfilessubdirs</var> is true. <em>since Ant 1.8.0</em>.</td>
+ <td>1.4</td>
+ <td>No</td>
+ </tr>
+ <tr>
+ <td>postProcessGeneratedJavadocs</td>
+ <td>Whether to post-process the generated javadocs in order to mitigate
+ CVE-2013-1571. <em>Since Ant 1.9.2</em><br/> There is a frame injection attack possible in
+ javadocs generated by Oracle JDKs prior to Java 7 update 25
+ (<a href="https://www.oracle.com/technetwork/java/javase/7u25-relnotes-1955741.html#jpi-upt"
+ target="_top">details</a>). When this flag is set to <q>true</q>, Ant will check whether the
+ docs are vulnerable and will try to fix them.</td>
+ <td>1.4</td>
+ <td>No; defaults to <q>true</q></td>
</tr>
+ <tr>
- <td valign="top">modulesourcepath</td>
- <td valign="top">Specify where to find module source files
- <em>since Ant 1.9.14</em></td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
++ <td>modulesourcepath</td>
++ <td>Specify where to find module source files
++ <em>since Ant 1.10.6</em></td>
++ <td>all</td>
++ <td>No</td>
+ </tr>
+ <tr>
- <td valign="top">modulesourcepathref</td>
- <td valign="top">Specify where to find module source files by <a
++ <td>modulesourcepathref</td>
++ <td>Specify where to find module source files by <a
+ href="../using.html#references">reference</a> to a PATH defined elsewhere.
- <em>since Ant 1.9.14</em></td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
++ <em>since Ant 1.10.6</em></td>
++ <td>all</td>
++ <td>No</td>
+ </tr>
+ <tr>
- <td valign="top">modulepath</td>
- <td valign="top">Specify where to find module files
- <em>since Ant 1.9.14</em></td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
++ <td>modulepath</td>
++ <td>Specify where to find module files
++ <em>since Ant 1.10.6</em></td>
++ <td>all</td>
++ <td>No</td>
+ </tr>
+ <tr>
- <td valign="top">modulepathref</td>
- <td valign="top">Specify where to find module files by <a
++ <td>modulepathref</td>
++ <td>Specify where to find module files by <a
+ href="../using.html#references">reference</a> to a PATH defined elsewhere.
- <em>since Ant 1.9.14</em></td>
- <td align="center" valign="top">all</td>
- <td align="center" valign="top">No</td>
++ <em>since Ant 1.10.6</em></td>
++ <td>all</td>
++ <td>No</td>
+ </tr>
</table>
-<h4><a name="groupattribute">Format of the group attribute</a></h4>
-<p>The arguments are comma-delimited. Each single argument is 2
-space-delimited strings, where the first one is the group's title and
-the second one a colon delimited list of packages.</p>
-<p>If you need to specify more than one group, or a group whose title
-contains a comma or a space character, using <a
-href="#groupelement">nested group elements</a> is highly
+<h4 id="groupattribute">Format of the group attribute</h4>
+<p>The arguments are comma-delimited. Each single argument is 2 space-delimited strings, where the
+first one is the group's title and the second one a colon delimited list of packages.</p>
+<p>If you need to specify more than one group, or a group whose title contains a comma or a space
+character, using <a href="#groupelement">nested <code>group</code> elements</a> is highly
recommended.</p>
<p>E.g.:</p>
-<pre> group="XSLT_Packages org.apache.xalan.xslt*,XPath_Packages org.apache.xalan.xpath*"</pre>
+<pre>group="XSLT_Packages org.apache.xalan.xslt*,XPath_Packages org.apache.xalan.xpath*"</pre>
<h3>Parameters specified as nested elements</h3>
@@@ -567,20 -643,38 +604,38 @@@ filesets, filelists or paths) will be p
<h5>Parameters</h5>
Same as for <code>package</code>.
+ <h4>module</h4>
-<p><em>since Ant 1.9.14</em></p>
++<p><em>since Ant 1.10.6</em></p>
+ <p>Same as one entry in the list given by <code>modulenames</code>.</p>
+
+ <h5>Parameters</h5>
+ <table width="90%" 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>
++ <td scope="col"><b>Attribute</b></td>
++ <td scope="col"><b>Description</b></td>
++ <td scope="col"><b>Required</b></td>
+ </tr>
+ <tr>
- <td valign="top">name</td>
- <td valign="top">The module name</td>
- <td align="center" valign="top">Yes</td>
++ <td>name</td>
++ <td>The module name</td>
++ <td>Yes</td>
+ </tr>
+ </table>
+
<h4>source</h4>
-<p>Same as one entry in the list given by <code>sourcefiles</code>.</p>
+<p>Same as one entry in the list given by <var>sourcefiles</var>.</p>
<h5>Parameters</h5>
-<table width="90%" border="1" cellpadding="2" cellspacing="0">
+<table class="attr">
<tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
+ <th scope="col">Attribute</th>
+ <th scope="col">Description</th>
+ <th scope="col">Required</th>
</tr>
<tr>
- <td valign="top">file</td>
- <td valign="top">The source file to document</td>
- <td align="center" valign="top">Yes</td>
+ <td>file</td>
+ <td>The source file to document</td>
+ <td>Yes</td>
</tr>
</table>
@@@ -786,36 -884,38 +841,38 @@@ target="_top">the default taglets</a>.<
</tr>
</table>
- <h4>sourcepath, classpath and bootclasspath</h4>
- <p><code>Javadoc</code>'s <var>sourcepath</var>, <var>classpath</var> and <var>bootclasspath</var>
- attributes are <a href="../using.html#path">path-like structure</a> and can also be set via
- nested <code>sourcepath</code>, <code>classpath</code> and <code>bootclasspath</code> elements
- respectively.</p>
+ <h4>sourcepath, classpath, bootclasspath, modulepath, modulesourcepath</h4>
+ <p><code>Javadoc</code>'s <i>sourcepath</i>, <i>classpath</i>,
+ <i>bootclasspath</i>, <i>modulepath</i>, and <i>modulesourcepath</i>
+ attributes are <a href="../using.html#path">PATH like structure</a>
+ and can also be set via nested <i>sourcepath</i>,
+ <i>classpath</i>, <i>bootclasspath</i>, <i>modulepath</i>,
+ and <i>modulesourcepath</i> elements respectively.</p>
<h4>arg</h4>
-
-<p>Use nested <code><arg></code> to specify additional
-arguments. See <a href="../using.html#arg">Command line
-arguments</a>. <em>Since Ant 1.6</em></p>
+<p><em>Since Ant 1.6</em></p>
+<p>Use nested <code><arg></code> to specify additional arguments.
+See <a href="../using.html#arg">Command line arguments</a>.</p>
<h3>Example</h3>
-<pre> <javadoc packagenames="com.dummy.test.*"
- sourcepath="src"
- excludepackagenames="com.dummy.test.doc-files.*"
- defaultexcludes="yes"
- destdir="docs/api"
- author="true"
- version="true"
- use="true"
- windowtitle="Test API">
- <doctitle><![CDATA[<h1>Test</h1>]]></doctitle>
- <bottom><![CDATA[<i>Copyright &#169; 2000 Dummy Corp. All Rights Reserved.</i>]]></bottom>
- <tag name="todo" scope="all" description="To do:"/>
- <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://docs.oracle.com/javase/7/docs/api/" packagelistLoc="C:\tmp"/>
- <link href="http://docs.oracle.com/javase/7/docs/api/"/>
- </javadoc></pre>
+<pre>
+<javadoc packagenames="com.dummy.test.*"
+ sourcepath="src"
+ excludepackagenames="com.dummy.test.doc-files.*"
+ defaultexcludes="yes"
+ destdir="docs/api"
+ author="true"
+ version="true"
+ use="true"
+ windowtitle="Test API">
+ <doctitle><![CDATA[<h1>Test</h1>]]></doctitle>
+ <bottom><![CDATA[<i>Copyright &#169; 2000 Dummy Corp. All Rights Reserved.</i>]]></bottom>
+ <tag name="todo" scope="all" description="To do:"/>
+ <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="https://docs.oracle.com/javase/8/docs/api/" packagelistLoc="C:\tmp"/>
+ <link href="https://docs.oracle.com/javase/8/docs/api/"/>
+</javadoc></pre>
<p>is the same as</p>
http://git-wip-us.apache.org/repos/asf/ant/blob/872a9bcd/src/main/org/apache/tools/ant/taskdefs/Javadoc.java
----------------------------------------------------------------------
diff --cc src/main/org/apache/tools/ant/taskdefs/Javadoc.java
index dc08876,999b103..13b8fed
--- a/src/main/org/apache/tools/ant/taskdefs/Javadoc.java
+++ b/src/main/org/apache/tools/ant/taskdefs/Javadoc.java
@@@ -448,19 -445,22 +448,22 @@@ public class Javadoc extends Task
private boolean failOnWarning = false;
private Path sourcePath = null;
private File destDir = null;
- private final Vector<SourceFile> sourceFiles = new Vector<SourceFile>();
- private final Vector<PackageName> packageNames = new Vector<PackageName>();
- private final Vector<PackageName> excludePackageNames = new Vector<PackageName>(1);
- private final List<PackageName> moduleNames = new ArrayList<PackageName>();
+ private final List<SourceFile> sourceFiles = new Vector<>();
+ private final List<PackageName> packageNames = new Vector<>();
+ private final List<PackageName> excludePackageNames = new Vector<>(1);
++ private final List<PackageName> moduleNames = new ArrayList<>();
private boolean author = true;
private boolean version = true;
private DocletInfo doclet = null;
private Path classpath = null;
private Path bootclasspath = null;
+ private Path modulePath = null;
+ private Path moduleSourcePath = null;
private String group = null;
private String packageList = null;
- private final Vector<LinkArgument> links = new Vector<LinkArgument>();
- private final Vector<GroupArgument> groups = new Vector<GroupArgument>();
- private final Vector<Object> tags = new Vector<Object>();
+ private final List<LinkArgument> links = new Vector<>();
+ private final List<GroupArgument> groups = new Vector<>();
+ private final List<Object> tags = new Vector<>();
private boolean useDefaultExcludes = true;
private Html doctitle = null;
private Html header = null;
@@@ -567,6 -567,88 +570,88 @@@
}
/**
+ * Specify where to find modules
+ *
+ * @param src a Path instance containing the modules.
+ *
- * @since Ant 1.9.14
++ * @since Ant 1.10.6
+ */
+ public void setModulePath(final Path mp) {
+ if (modulePath == null) {
+ modulePath = mp;
+ } else {
+ modulePath.append(mp);
+ }
+ }
+
+ /**
+ * Create a path to be configured with the locations of the module
+ * files.
+ *
+ * @return a new Path instance to be configured by the Ant core.
+ *
- * @since Ant 1.9.14
++ * @since Ant 1.10.6
+ */
+ public Path createModulePath() {
+ if (modulePath == null) {
+ modulePath = new Path(getProject());
+ }
+ return modulePath.createPath();
+ }
+
+ /**
+ * Adds a reference to a path defined elsewhere that defines the module path.
+ *
+ * @param r the reference containing the module path definition.
+ *
- * @since Ant 1.9.14
++ * @since Ant 1.10.6
+ */
+ public void setModulePathref(final Reference r) {
+ createModulePath().setRefid(r);
+ }
+
+ /**
+ * Specify where to find sources for modules
+ *
+ * @param src a Path instance containing the sources for modules.
+ *
- * @since Ant 1.9.14
++ * @since Ant 1.10.6
+ */
+ public void setModuleSourcePath(final Path mp) {
+ if (moduleSourcePath == null) {
+ moduleSourcePath = mp;
+ } else {
+ moduleSourcePath.append(mp);
+ }
+ }
+
+ /**
+ * Create a path to be configured with the locations of the module
+ * source files.
+ *
+ * @return a new Path instance to be configured by the Ant core.
+ *
- * @since Ant 1.9.14
++ * @since Ant 1.10.6
+ */
+ public Path createModuleSourcePath() {
+ if (moduleSourcePath == null) {
+ moduleSourcePath = new Path(getProject());
+ }
+ return moduleSourcePath.createPath();
+ }
+
+ /**
+ * Adds a reference to a path defined elsewhere that defines the module source path.
+ *
+ * @param r the reference containing the module source path definition.
+ *
- * @since Ant 1.9.14
++ * @since Ant 1.10.6
+ */
+ public void setModuleSourcePathref(final Reference r) {
+ createModuleSourcePath().setRefid(r);
+ }
+
+ /**
* Set the directory where the Javadoc output will be generated.
*
* @param dir the destination directory.
@@@ -620,6 -702,23 +705,21 @@@
}
/**
+ * Set the module names to be processed.
+ *
+ * @param modules a comma separated list of module names
+ *
- * @since Ant 1.9.14
++ * @since Ant 1.10.6
+ */
+ public void setModulenames(final String modules) {
- final StringTokenizer tok = new StringTokenizer(modules, ",");
- while (tok.hasMoreTokens()) {
- final String m = tok.nextToken();
++ for (String m : modules.split(",")) {
+ final PackageName mn = new PackageName();
+ mn.setName(m);
+ addModule(mn);
+ }
+ }
+
+ /**
* Add a single package to be processed.
*
* If the package name ends with ".*" the Javadoc task
@@@ -632,6 -731,17 +732,17 @@@
}
/**
+ * Add a single module to be processed.
+ *
+ * @param mn the module name
+ *
- * @since Ant 1.9.14
++ * @since Ant 1.10.6
+ */
+ public void addModule(final PackageName mn) {
+ moduleNames.add(mn);
+ }
+
+ /**
* Set the list of packages to be excluded.
*
* @param packages a comma separated list of packages to be excluded.
@@@ -1850,11 -1975,11 +1962,11 @@@
}
private void checkPackagesToDoc(
- final Vector<String> packagesToDoc, final Vector<SourceFile> sourceFilesToDoc) {
- if (packageList == null && packagesToDoc.size() == 0
- && sourceFilesToDoc.size() == 0 && moduleNames.isEmpty()) {
+ final List<String> packagesToDoc, final List<SourceFile> sourceFilesToDoc) {
+ if (packageList == null && packagesToDoc.isEmpty()
- && sourceFilesToDoc.isEmpty()) {
- throw new BuildException(
- "No source files and no packages have been specified.");
++ && sourceFilesToDoc.isEmpty() && moduleNames.isEmpty()) {
+ throw new BuildException("No source files, no packages and no modules have "
+ + "been specified.");
}
}
@@@ -2479,6 -2664,29 +2591,23 @@@
return fileContents;
}
+ private void doModuleArguments(Commandline toExecute) {
+ if (!moduleNames.isEmpty()) {
- StringBuilder sb = null;
- for (PackageName mn : moduleNames) {
- if (sb == null) {
- sb = new StringBuilder(mn.getName());
- } else {
- sb.append(",").append(mn.getName());
- }
- }
+ toExecute.createArgument().setValue("--module");
- toExecute.createArgument().setValue(sb.toString());
++ toExecute.createArgument()
++ .setValue(moduleNames.stream().map(PackageName::getName)
++ .collect(Collectors.joining(",")));
+ }
+ if (modulePath != null) {
+ toExecute.createArgument().setValue("--module-path");
+ toExecute.createArgument().setPath(modulePath);
+ }
+ if (moduleSourcePath != null) {
+ toExecute.createArgument().setValue("--module-source-path");
+ toExecute.createArgument().setPath(moduleSourcePath);
+ }
+ }
+
private class JavadocOutputStream extends LogOutputStream {
JavadocOutputStream(final int level) {
super(Javadoc.this, level);