Javadoc and ANT

Author: Kasper B. Graversen, 11/12/07
Keywords: ANT, Build script, Javadoc
Abstract: This article introduces the art of generating Javadocs using ANT and extending the Javadoc with new tags.
subscribe to my RSS feed


Bookmark and Share


Javadoc and ANT

Generating Javadocs in ANT is rather straight forward. Probably, you'll spend the most time on getting the layout correct. In the most basic case, you simply point the javadoc generator at your source code and tell it which classes to exclude (e.g. your test classes). You can also consider generating several versions of your Javadoc. One with copyright notices, and only public/protected methods, and an in-house version with the copyright notices omitted and including private and deprecated methods.

Our first example shows the generation of Javadocs for public methods excluding mock packages and test packages. This is only needed if these classes are stored in the same directory as the business classes. Older setups seems predominant in such setup. With more intelligent editors such as Eclipse, however, it is easy to set up multiple source paths effectively separating test code from production code. 
<target name="javadoc">
    <javadoc
        excludepackagenames="org.test.supercsv.mock"
          access="public"
           destdir="${dir.javadoc}"
           author="true"
           version="true"
           use="true"
           windowtitle="org.Super.CSV.API"
       >

        <fileset dir="${dir.src}" defaultexcludes="yes">
            <include name="**/*.java"/>
            <exclude name="org/test/**/*.java" />
        </fileset>
    </javadoc>
</target>
This next example is a bit different, in that relies on a task to insert copyright licenses (see inserting copyright notices with ant) and utilized some of these constants in elements of the generated javadoc pages. 
<target name="javaDoc" depends="insertLicense">
   <javadoc sourcepath="${dir.build}/src"
            destdir="${dir.docs}/javadoc"
            packagenames="com.foo.*"
            doctitle="${officialName} ${version} API Documentation"
            bottom="${officialName} ${version} API Documentation - Copyright ${year} ${copyright}"
            header="${officialName} ${version} API Documentation - Copyright ${year} ${copyright}"
            footer="${officialName} ${version} API Documentation - Copyright ${year} ${copyright}"
             />
</target>
If you want to use HTML tags in theh title, header, bottom etc, remember that you are writing in XML and thus you need to wrap your input with a CDATA ala 
<javadoc>
    <doctitle><![CDATA[<h1>My company Name</h1>]]></doctitle>
</javadoc>

Adding new @tags to the javadoc

For most cases, it is straight forward to extend your javadocs with new @tags such as @copyright. A practical use is for documenting use of design by contract (see Bertrand Meyer) using the tags @precondition, @postcondition and @invariant. In order to do this, simple nest the list of extra tags to the javadoc tag. 
<javadoc>
    <tag name="precondition" scope="all" description="Precondition:"/>
    <tag name="postcondition" scope="all" description="Postcondition:"/>
    <tag name="invariant" scope="all" description="Invariant:"/>
    <tag name="copyright" scope="all" description="Copyright:"/>
</javadoc>

Properly linking to other code

A really annoying thing about the Javadoc generator is that the standard setting does not have a notion of the "standard java API". This means your method

public void foo(String name)

in the javadoc output becomes

public void foo(java.lang.String name)

Fortunately, you can easily solve this by telling the javadoc generator to take whatever API into consideration. For the standard JDK 5 API use 
<javadoc>
    <link href="http://java.sun.com/j2se/1.5.0/docs/api/"/>
</javadoc>
You may insert as many references as you want..



Comments

If you have any comments to this article, please drop me a mail at firstclassthoughts at gmail dot com please indicate if I can't publish whole or parts of your comment on the site.


If you like this site consider subscribing to my RSS feed or how about subscribing by Email.


Help spread the word

Share this post on your favorite social bookmarking sites:
If you enjoyed this article, found it thought provoking, educative or otherwise good, please link to this page from your page or social bookmarking page. If you have any texts you think are worth publishing on First Class Thoughts, don't hesitate to send me a mail! Quality always welcome.


Bookmark and Share


The most recent contributions
28/07/09 Magic in mathematics II Fun with the number cyclic numbers, and specifically with 142857 as it is the smallest of such numbers.
13/07/09 My top 8 time-saving Firefox shortcuts This article presents my favorite top 8 time-saving shortcuts in Firefox 3.0 and Firefox 3.5. Get to know these and you'll be saving a lot of time. They have been ordered by "the element of most surprise"
20/05/09 Board Game Jungle speed / Arriba Review of the cool game "Jungle Speed" aka. "Arriba".
16/05/09 Danish Twin words "Twin words" are words that not only have multiple meanings, they must be composed next to each other in meaningful sentences. This article explores the concept of twin words.
Nothing of interest? Try browsing the entire article archive...