DocFlex/Javadoc 1.5, the rapid doclet development tool

FILIGRIS WORKS is pleased to announce the release of DocFlex/Javadoc version 1.5.3.

DocFlex/Javadoc is both a multi-format Javadoc Doclet and a rapid doclet development tool, which allows easy creation of professional quality Java API documentation generated by Javadoc in various output formats.

For lots more information, please visit the product home page:

Also, read in this article:

About DocFlex/Javadoc

DocFlex/Javadoc is an innovative tool for rapid development of professional quality Javadoc doclets.

Doclets are programmed in the form templates using a graphic Template Designer. Further, the main template is passed as an argument to a special interpreter.

The template interpreter (called DocFlex Doclet) at the same time serves the role of an ordinary Javadoc doclet. So, it is specified on the Javadoc command line with the -doclet option.

Once launched by Javadoc, the DocFlex Doclet connects to the Doclet API and by interpreting the instructions contained in the templates generates the output documentation. In that way, the pair {DocFlex Doclet + template set} works as a separate and unique Javadoc doclet.

What can be generated with such a doclet?

Almost anything! For instance, the standard template set (included in DocFlex/Javadoc) is able to generate:

The following screenshots show a framed HTML (left) and single-file HTML (right) demo documentation generated with the standard templates (click to see the live HTML):
Framed HTML documentation
Singe-file HTML documentation
These screenshots show pages of the generated demo RTF documentation (click to enlarge):
RTF JavaDoc RTF JavaDoc
RTF JavaDoc RTF JavaDoc

Main Features

System Requirements

DocFlex/Javadoc requires the Javadoc Tool delivered with one of the following Java Development Kits: Since DocFlex/Javadoc is a pure Java application (the Template Designer and Doclet GUI are based entirely on Swing), it is supposed to work on any operating system with the installed JDK.

Specifically, the software available for downloads includes both MS Windows BAT files and Linux shell script files to run DocFlex/Javadoc immediately on those operating systems.

A sample Ant buildfile is also supplied to demonstrate integration of DocFlex Doclet with the Apache Ant.

Simultaneous Support of Java 1.4 and Java 5

As you may know, since JDK 5.0, the Doclet API has been extended to reflect the new language features introduced in Java 5. Because of this, a doclet developed for Java 5 won't work under Java 1.4 (otherwise is possible, of course).

However, as we found (after the preliminary v1.5 beta release), the Java 1.4 appears to be still well in use. So, we have finally decided in DocFlex/Javadoc v1.5.x to support both Java versions (i.e. the new Doclet API 1.5 and the old Doclet API 1.4).

Since the binaries compiled for Java 5 are not compatible with Java 1.4, now, DocFlex/Javadoc v1.5.x (both editions) includes two Java libraries: the one compiled for Java 5+ and another one compiled for Java 1.4.

The Doclet DSM, on which any DocFlex/Javadoc templates are based, is always the same. That is, the Java 5 functionality (i.e. the mapping of entire Doclet API 1.5 on a virtual XML document model) is present in both libraries. However, in the version compiled for Java 1.4, everything concerned Java 5 is emulated by the Doclet DSM Driver itself.

As a result, any templates designed for either Java version will work fine under both Java 5+ and Java 1.4 as well. The templates simply won't "notice" the difference!

What are Templates?

The DocFlex/Javadoc templates are actually programs. The idea behind the template approach is the following.

If you consider how almost any Java library that generates something (and not only generates -- for instance, powers a GUI system) works, you will notice that, basically, it may be described as the following:

  1. First, we need to create a certain object representation of some controlling structure (using special classes and methods of that library).
  2. Further, we call an interpreter included in that library and pass to it that controlling structure along with some data source we want to process, e.g. some data file, some interface or whatsoever. (Actually, such an interpreter may be started just by calling some member method of the root object representing that controlling structure. For instance, in case of a GUI system, this may be as simple as
  3. Finally, the interpreter processes that controlling structure and produces from the data source some useful output (or shows a GUI).
What the actual programming is all about here, when using such a system, is the first step. We need to encode the creation of that controlling structure! (And this may be a piece of work indeed...)

Now, let's imagine that such a controlling structure is serialized to a file (and, therefore, can be created from it). What is that file, then? One may call it a "template"!

But if that is a template, why not to create and edit it using some template designer GUI? That approach has a number of advantages:

DocFlex/Javadoc is exactly an implementation of that idea!

The following screenshot shows the class.tpl template open in the Template Designer (click to enlarge):

Template Designer with “class.tpl” template
This template is included in the standard template set and generates the bulk of the documentation.

Standard Template Set

DocFlex/Javadoc includes a ready-to-use template set, which is able to generate an HTML JavaDoc looking very much similar to that produced by the Standard Javadoc Doclet. In addition, the same template set can generate unique quality RTF documentation (that the standard doclet cannot)!

Another unique feature supported by the standard template set (and not available in the standard Javadoc) is a possibility to exclude from the generated documentation the classes, fields and methods marked with special tags and annotations. This gives you incredible flexibility over how you can document your Java project!

Here is an example of the framed HTML documentation generated with the standard template set (click to see the real HTML):

Framed HTML documentation
Everything you see in that documentation has been programmed entirely in the templates!

Currently, the standard template set consists of only 15 template files (plus one icon), which in total occupy 390 KB. That is all what was needed to program the entire Java API documentation generator!

In comparison, the recent Java implementation of the Javadoc's standard HTML doclet (whose Java sources can be found, for instance, at -> jdk-6u2-fcs-src-b05-jrl-22_jun_2007.jar -> j2se/src/share/classes/com/sun/tools/doclets/) consists of 141 files occupying 979 KB in total.

What's more, unlike the standard doclet's Java sources, all templates provided with DocFlex/Javadoc are free for any changes and modifications. Using the Template Designer, you can easily change the look & feel of the generated JavaDoc, insert your company's logotype and so on, as well as to program eventually whatever you wish (so much as you are willing to understand how everything works). Further, you will be free to use your created/modified templates for whatever purpose you need.

Doclet GUI

A doclet implemented as {DocFlex Doclet + template set} is controlled by lots of settings, which include: All such settings can be assigned using options on the Javadoc command line (most, actually, have their default values). However, in addition to it, DocFlex Doclet provides a much more user-friendly way to specify everything.

When no -nodialog option has been specified on the command line, as soon as Javadoc finishes parsing Java sources and calls the doclet to generate the output, the DocFlex Doclet invokes the following dialog (click to enlarge):

Doclet Dialog
Here, you can fill in all required settings of the DocFlex Doclet: the template, the output format, the output file/destination.

The additional settings, such as template parameters and the output format options can be assigned in the special property inspector dialogs invoked by clicking the buttons on the right (click to enlarge):

Template Parameter Inspector
RTF Option Inspector
The bottom panel in the inspector dialog shows the HTML-preformatted description of each parameter or format-specific generator option.

When all settings are prepared, you can start the generation by clicking <Run> button. Then, the generator dialog will transform itself to show the generation progress (click to enlarge):

Generating Output
You can stop the generation at any moment by clicking <Cancel> button.

Once the generation has finished (or cancelled), the generator dialog transforms itself back into its initial state. After that, you can change any settings and start the generator again with a new (or modified) template set. This, in effect, allows changing your doclet on the fly. At that, you won't need to restart the whole Javadoc. All the memory representation of your Java project provided via the Doclet API will remain the same.

This unique capability makes possible extremely fast designing and modification of your templates. Just change something in the Template Designer, restart the generator and you can see how it looks now in the result output!


This original article can be found at:

DocFlex/Javadoc home page:

Free downloads: