vDoclet - Intro

What is vDoclet?

vDoclet is a Java code-generation framework. It takes Java source-code, annotated with custom Javadoc tags, and uses Velocity templates to produce a number of output files.

vDoclet uses "javadoc" to parse a set of Java source-files, and constructs a in-memory "DocInfo" model of the source-code. The resulting DocInfo is passed to a "control" template, which invokes other templates to generate output files.

Where can I get it?

vDoclet can be downloaded from the SourceForge project page.

The latest development version can be downloaded using anonymous CVS, as follows:

    $ CVS_VDOCLET=":pserver:anonymous@cvs.vdoclet.sourceforge.net:/cvsroot/vdoclet"
    $ cvs -d $CVS_VDOCLET login 
    $ cvs -d $CVS_VDOCLET co vdoclet

Prerequisites

To build vDoclet from sources, you will need:

A Java 2 SDK, e.g. J2SE-1.3
Jakarta Ant, v1.3 or better
JUnit, v3.7 or better

Building vDoclet

To build vDoclet, and run the basic unit-tests, type:

    $ ant

To generate the binary distribution, complete with documentation etc, type:

    $ ant dist

Running vDoclet

The easiest way to run vDoclet is using the Ant task provided. For example:

    <target name="vdoclet">
        <taskdef name="vdoclet"
                 classname="vdoclet.ant.VDocletTask">
            <classpath id="vdoclet.classpath">
                <pathelement location="lib/vdoclet.jar" />
                <pathelement location="lib/velocity-dep.jar" />
                <pathelement location="lib/qdox-current.jar" />
            </classpath>
        </taskdef>
    </target>

    <target name="ejb/generate" depends="vdoclet">
        <vdoclet srcDir="ejb/java"
                 destDir="build/ejb/java"
                 template="vdoclet/ejb/generate.vm">
            <classpath>
                <path refid="j2ee.classpath" />
            </classpath>
        </vdoclet>
    </target>

This example would process Java source-code in the "ejb/java" directory using the "vdoclet/ejb/generate.vm" template, and places the results in "build/ejb/java".

Template-loading

It's important to note that vDoclet loads templates as resources from the Java classpath, rather than from the current directory, or the source-directory. In the example above, "vdoclet/ejb/generate.vm" is a template bundled with vDoclet.

Examples

A couple of examples are included with vDoclet. In each case, the example can be run by invoking the Ant target of the same name, e.g.

    $ ant smoketest

and output will be found under "build/examples".

"smoketest" processes the vDoclet source-code itself, and produces a file per class that summarises the class structure.
"ejbtest" runs vDoclet/EJB on the sample code in "examples/ejbtest", generating interfaces and deployment-descriptors, and compiles these to create an EJB-jar file.

Getting Involved

Development of vDoclet is hosted at SourceForge. See the project page for more details.

If you have questions regarding vDoclet, we invite you to join the vdoclet-user mailing-list.

Acknowledgements

Thanks to Cortex eBusiness, my employers during the initial development of vDoclet, who allowed me to release it as open-source.

Regards to SourceForge for hosting the vDoclet project.

Thanks to Joe Walnes et al. for QDox, which vDoclet uses to prise information from your Java source-code.

A tip of the hat to the Jakarta-Velocity team, who make a damn fine template engine.

Respect to Rickard Öberg and the XDoclet team, who popularised the practice of Javadoc-based code-generation.