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.

How does it work?

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:

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".

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.

SourceForge.net 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.

Powered by Velocity 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.