| <html> |
| |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"> |
| <title>Ant User Manual</title> |
| </head> |
| |
| <body> |
| |
| <h2><a name="javadoc">Javadoc/<i>Javadoc2</i></a></h2> |
| <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>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>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 |
| application and will be called infrequently.</p> |
| <p>NOTE: the packagelist attribute allows you to specify the list of packages to |
| document outside of the Ant file. It's a much better practice to include everything |
| inside the build.xml file. This option was added in order to make it easier to |
| migrate from regular makefiles, where you would use this option of javadoc. |
| The packages listed in packagelist are not checked, so the task performs even |
| if some packages are missing or broken. Use this option if you wish to convert from |
| an existing makefile. Once things are running you should then switch to the regular |
| 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> |
| <h3>Parameters</h3> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Availability</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </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="2">At least one of the two or nested |
| <code><sourcepath></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> |
| </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> |
| </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> |
| </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><source></code> or <code><package></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> |
| </tr> |
| <tr> |
| <td valign="top">packageList</td> |
| <td valign="top">The name of a file containing the packages to process</td> |
| <td align="center" valign="top">all</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">classpath</td> |
| <td valign="top">Specify where to find user class files</td> |
| <td align="center" valign="top">all</td> |
| <td align="center" valign="top">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">1.2</td> |
| <td align="center" valign="top">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> |
| </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">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">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">No</td> |
| </tr> |
| <tr> |
| <td valign="top">access</td> |
| <td valign="top">Access mode: one of <code>public</code>, <code>protected</code>, |
| <code>package</code>, or <code>private</code></td> |
| <td align="center" valign="top">all</td> |
| <td align="center" valign="top">No (default <code>protected</code>)</td> |
| </tr> |
| <tr> |
| <td valign="top">Public</td> |
| <td valign="top">Show only public classes and members</td> |
| <td align="center" valign="top">all</td> |
| <td align="center" valign="top">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> |
| </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> |
| </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> |
| </tr> |
| <tr> |
| <td valign="top">Old</td> |
| <td valign="top">Generate output using JDK 1.1 emulating doclet</td> |
| <td align="center" valign="top">1.2</td> |
| <td align="center" valign="top">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">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">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> |
| </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> |
| </tr> |
| <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">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> |
| </tr> |
| <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">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">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">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">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">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">No</td> |
| </tr> |
| <tr> |
| <td valign="top">link</td> |
| <td valign="top">Create links to javadoc output at the given URL</td> |
| <td align="center" valign="top">1.2</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">linkoffline</td> |
| <td valign="top">Link to docs at <url> using package list at |
| <url2> - separate the URLs by using a space character.</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">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> |
| </tr> |
| <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">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> |
| </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> |
| </tr> |
| <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">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">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 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 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">No</td> |
| </tr> |
| <tr> |
| <td valign="top">charset</td> |
| <td valign="top">FUTURE: Charset for cross-platform viewing of generated |
| documentation</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">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">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">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">1.2</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;.</td> |
| <td align="center" valign="top">1.2</td> |
| <td align="center" valign="top">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> |
| </tr> |
| <tr> |
| <td valign="top">excludepackagenames</td> |
| <td valign="top">comma separated list of packages you don't want |
| docs for.</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. |
| (<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> |
| </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 |
| recommended.</p> |
| <p>E.g., |
| <pre> group="XSLT_Packages org.apache.xalan.xslt*,XPath_Packages org.apache.xalan.xpath*" |
| </pre></p> |
| |
| <h3>Parameters specified as nested elements</h3> |
| |
| <h4>package</h4> |
| <p>Same as one entry in the list given by <code>packagenames</code>.</p> |
| |
| <h5>Parameters</h5> |
| <table width="60%" border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">name</td> |
| <td valign="top">The package name (may be a wildcard)</td> |
| <td align="center" valign="top">Yes</td> |
| </tr> |
| </table> |
| |
| <h4>excludepackage</h4> |
| <p>Same as one entry in the list given by <code>excludepackagenames</code>.</p> |
| |
| <h5>Parameters</h5> |
| Same as for <code>package</code>. |
| |
| <h4>source</h4> |
| <p>Same as one entry in the list given by <code>sourcefiles</code>.</p> |
| |
| <h5>Parameters</h5> |
| <table width="60%" border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">file</td> |
| <td valign="top">The source file to document</td> |
| <td align="center" valign="top">Yes</td> |
| </tr> |
| </table> |
| |
| <h4>doctitle</h4> |
| |
| <p>Same as the <code>doctitle</code> attribute, but you can nest text |
| inside the element this way.</p> |
| |
| <h4>header</h4> |
| |
| <p>Similar to <code><doctitle></code>.</p> |
| |
| <h4>footer</h4> |
| |
| <p>Similar to <code><doctitle></code>.</p> |
| |
| <h4>bottom</h4> |
| |
| <p>Similar to <code><doctitle></code>.</p> |
| |
| <h4>link</h4> |
| <p>Create link to javadoc output at the given URL. This performs the |
| same role as the link and linkoffline attributes. You can use either |
| syntax (or both at once), but with the nested elements you can easily |
| specify multiple occurrences of the arguments.</p> |
| |
| <h5>Parameters</h5> |
| <table width="60%" border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">href</td> |
| <td valign="top">The URL for the external documentation you wish to link to</td> |
| <td align="center" valign="top">Yes</td> |
| </tr> |
| <tr> |
| <td valign="top">offline</td> |
| <td valign="top">True if this link is not available online at the time of |
| generating the documentation</td> |
| <td align="center" valign="top">No</td> |
| </tr> |
| <tr> |
| <td valign="top">packagelistLoc</td> |
| <td valign="top">The location to the directory containing the package-list file for |
| the external documentation</td> |
| <td align="center" valign="top">Only if the offline attribute is true</td> |
| </tr> |
| </table> |
| |
| <h4><a name="groupelement">group</a></h4> |
| <p>Separates packages on the overview page into whatever groups you |
| specify, one group per table. This performs the same role as the group |
| attribute. You can use either syntax (or both at once), but with the |
| nested elements you can easily specify multiple occurrences of the |
| arguments.</p> |
| |
| <h5>Parameters</h5> |
| <table width="60%" border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">title</td> |
| <td valign="top">Title of the group</td> |
| <td align="center" valign="top">Yes, unless nested <code><title></code> given</td> |
| </tr> |
| <tr> |
| <td valign="top">packages</td> |
| <td valign="top">List of packages to include in that group. Multiple packages are separated with ':'.</td> |
| <td align="center" valign="top">Yes, unless nested <code><package></code>s given</td> |
| </tr> |
| </table> |
| |
| <p>The title may be specified as a nested <code><title></code> element |
| with text contents, and the packages may be listed with nested |
| <code><package></code> elements as for the main task. |
| |
| <h4>doclet</h4> |
| <p>The doclet nested element is used to specify the doclet that javadoc will |
| use to process the input source files. A number of the standard javadoc arguments |
| are actually arguments of the standard doclet. If these are specified in the javadoc |
| task's attributes, they will be passed to the doclet specified in the |
| <code><doclet></code> nested element. Such attributes should only be specified, |
| therefore, if they can be interpreted by the doclet in use.</p> |
| |
| <p>If the doclet requires additional parameters, these can be specified with |
| <code><param></code> elements within the <code><doclet></code> |
| element. These paramaters are restricted to simple strings. An example usage |
| of the doclet element is shown below:</p> |
| |
| <pre> <javadoc ...> |
| <doclet name="theDoclet" |
| path="path/to/theDoclet"> |
| <param name="-foo" value="foovalue"/> |
| <param name="-bar" value="barvalue"/> |
| </doclet> |
| </javadoc> |
| </pre> |
| |
| <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> |
| |
| <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> |
| <group title="Group 1 Packages" packages="com.dummy.test.a*"/> |
| <group title="Group 2 Packages" packages="com.dummy.test.b*:com.dummy.test.c*"/> |
| <link offline="true" href="http://java.sun.com/products/jdk/1.2/docs/api/" packagelistLoc="C:\tmp"/> |
| <link href="http://developer.java.sun.com/developer/products/xml/docs/api/"/> |
| </javadoc></pre> |
| |
| <hr> |
| <p align="center">Copyright © 2000,2001 Apache Software Foundation. All rights |
| Reserved.</p> |
| |
| </body> |
| </html> |
| |