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 &quot;.

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>



    Ant. The Definitive Guide
    Ant: The Definitive Guide, 2nd Edition
    ISBN: 0596006098
    EAN: 2147483647
    Year: 2003
    Pages: 115
    Authors: Steve Holzner

    flylib.com © 2008-2017.
    If you may any questions please contact us: flylib@qtcs.net