Section 3.5. Documenting Code

3.5. Documenting Code

Creating applications in a commercial environment frequently means creating documentation, and Ant is up for that with the javadoc task. This task creates documentation using the Java javadoc tool, a process that involves compilation, which merits including this task in this chapter. This is one of the largest tasks in Ant because of the enormous number of javadoc options.

Here's an example, stored in the javadoc folder in the code for this book. Suppose you add a documentation-type comment to the Project.java file:

/** This application prints out "No worries." */ public class Project  {     public static void main(String args[])      {         System.out.println("No worries.");         } }

You can create Javadoc for the project using the javadoc task in a new target I'll name doc, which will put the generated Javadoc in a doc directory, as you see in Example 3-3.

Note the XML <![CDATA[...]> sections, which the build file uses to pass data to the javadoc tool.

Example 3-3. Creating javadoc (ch03/javadoc/build.xml)

<?xml version="1.0" ?> <project default="main">     <property name="message" value="Building the .jar file." />     <property name="src" location="source" />     <property name="docs" location="docs" />     <property name="output" location="bin" />     <target name="main" depends="init, compile, doc, compress">         <echo>             ${message}         </echo>     </target>        <target name="init">         <mkdir dir="${output}" />         <mkdir dir="${docs}" />     </target>        <target name="compile">         <javac srcdir="${src}" destdir="${output}" />     </target>     <target name="doc">         <javadoc              sourcefiles="${src}/Project.java"             destdir="${docs}"             author="true"             version="true"             use="true"             windowtitle="Project API">             <doctitle><![CDATA[<h1>Project API</h1>]]></doctitle>             <bottom><![CDATA[<i>Copyright &#169; 2005</i>]]></bottom>         </javadoc>     </target>     <target name="compress">         <jar destfile="${output}/Project.jar" basedir="${output}" includes="*.class" />     </target> </project>

You can see the javadoc task at work when the build file runs:

%ant Buildfile: build.xml init:     [mkdir] Created dir: /home/steven//ch03/javadoc/bin     [mkdir] Created dir: /home/steven//ch03/javadoc/docs compile:     [javac] Compiling 1 source file to /home/steven//ch03/javadoc/bin doc:   [javadoc] Generating Javadoc   [javadoc] Javadoc execution   [javadoc] Loading source file /home/steven//ch03/javadoc/source/Project.java...   [javadoc] Constructing Javadoc information...   [javadoc] Standard Doclet version 1.4.0   [javadoc] Building tree for all the packages and classes...   [javadoc] Building index for all the packages and classes...   [javadoc] Building index for all classes...   [javadoc] Generating /home/steven//ch03/javadoc/docs/stylesheet.css... compress:       [jar] Building jar: /home/steven//ch03/javadoc/bin/Project.jar main:      [echo]      [echo]             Building the .jar file.      [echo] BUILD SUCCESSFUL Total time: 10 seconds

And you can see the index.html Javadoc result in Figure 3-1. Note the message "This application prints out `No worries.'"

Figure 3-1. New Javadoc for the project

You can see the huge number of attributes of this task in Table 3-9.

Since the javadoc tool calls the System.exit method, javadoc cannot be run inside the same JVM as Ant. For this reason, javadoc always forks the JVM.

Table 3-9. The javadoc task's attributes

Attribute	Description	Required	Default
access	Sets the access mode; you can use these values: public, protected, package, or private.	No	protected
additionalparam	Specifies additional parameters for the javadoc command line. Any parameters with spaces should be quoted using ".	No
author	Specifies you want to include @author paragraphs.	No
bootclasspath	Specifies you want to override the classpath set by the boot class loader.	No
bootclasspathref	Specifies you want to override class file references set by the boot class loader.	No
bottom	Sets the bottom text for each page.	No
breakiterator	Specifies you want to use the breakiterator algorithm, which is used in debugging. Set to yes or no.	No	no
charset	Specifies the character set to use.	No
classpath	Specifies the classpath for user class files.	No
classpathref	Specifies where to find user class files by reference.	No
defaultexcludes	Specifies whether you want default excludes to be used. Set to yes or no.	No	Default excludes are used.
destdir	Sets the output directory.	Yes
docencoding	Sets the output file encoding to use.	No
doclet	Specifies the class file used to start the doclet that will generate the documentation.	No
docletpath	Specifies the path to the doclet given by the -doclet option.	No
docletpathref	Specifies the path to the doclet given by the -doclet option by reference.	No
doctitle	Sets the title for the package index page.	No
encoding	Specifies the encoding of the source file.	No
excludepackagenames	Specifies the packages to exclude in the documentation. Give as a comma-separated list.	No
extdirs	Specifies you want to override the location of installed extensions.	No
failonerror	Specifies you want to stop the build process if the task exits with a non-zero return code.	No
footer	Specifies the footer text for each page.	No
group	Specifies you want to group particular packages in the generated overview page.	No
header	Specifies the header text you want to use for each page.	No
helpfile	Specifies the HTML help file you want to use, if any.	No
link	Specifies you want to create links to the Javadoc output at the given URL.	No
linkoffline	Specifies you want to link to the documentation at a specific URL using a package list at at another URL.	No
linksource	Indicates you want to generate hyperlinks to source files; available since Ant 1.6.	No	no
locale	Sets the locale to be used for generating documentation, such as "en_US".	No
maxmemory	Specifies the maximum amount of memory to allocate to the javadoc task.	No
nodeprecated	Specifies you do not want to include @deprecated information in the generated documentation.	No
nodeprecatedlist	Specifies you do not want to generate a deprecated list.	No
nohelp	Specifies you do not want to generate a link to help documentation.	No
noindex	Specifies you do not want to generate an index.	No
nonavbar	Specifies you don't want a navigation bar.	No
noqualifier	Allows you to use the -noqualifier argument. Set this attribute to "all" or a colon-separated list of packages. Available since Ant 1.6.	No
notree	Specifies you don't want a class hierarchy to be generated.	No
old	Specifies you want to generate output using JDK 1.1.	No
overview	Specifies where to get the overview documentation.	No
package	Indicates you want to include package/protected/public information.	No
packagelist	Specifies the name of a file that holds the packages to include in the generated documentation.	No
packagenames	Specifies a list of packages to include.	No
private	Specifies you want to show all private classes and members.	No
protected	Specifies you want to show all protected/public classes and members. This is the default.	No
public	Specifies you want to show only public classes and members.	No
serialwarn	Specifies you want to be warned about the @serial tag, if encountered.	No
source	Sets this attribute to 1.4 to document code that compiles using javac -source 1.4.	No
sourcefiles	Specifies the source files. Use a comma-separated list.	At least one of sourcepath, sourcefiles, sourcefiles, or a nested sourcepath, fileset, or packageset.
sourcepath	Specifies where to you want to find source files.	At least one of sourcepath, sourcefiles, sourcefiles, or a nested sourcepath, fileset or packageset.
sourcepathref	Specifies where you want to find source files by reference.	At least one of sourcepath, sourcefiles, sourcefiles, or a nested sourcepath, fileset, or packageset.
splitindex	Specifies you want to split the generated index into one file for each letter.	No
stylesheetfile	Specifies the CSS stylesheet you want to use.	No
use	Specifies you want to create class and package usage pages.	No
useexternalfile	Specifies whether the source filename(s) should be written to a temporary file. Set to yes or no.	No	no
verbose	Specifies you want this task to display messages of what it's doing.	No
version	Specifies you want to include @version paragraphs.	No
windowtitle	Sets the title of the browser window for the documentation.	No

For more on how to use the javadoc tool, look at the JDK documentation, available online at http://java.sun.com/j2se/1.4.2/docs/index.html.

Here's another example. This one passes Java packages starting with gui to javadoc to document them, excludes a few specific packages, sets the header text for each page, groups the packages gui.steve.api.* together on the first page under the title "Group 1 Packages," and includes a link to the Java 1.4.2 docs:

<javadoc destdir="api" version="true">     <packageset dir="code">         <include name="gui/**" />         <exclude name="gui/debug/**"/>     </packageset>     <header><![CDATA[Preliminary API Specification]]></header>     <doctitle><![CDATA[<h1>Test</h1>]]></doctitle>     <group title="Group 1 Packages" packages="gui.steve.api.*"/>     <link href="http://java.sun.com/j2se/1.4.2/docs/api/"/> </javadoc>