DocFlex/Javadoc 1.5 now fully supports Java 5

FILIGRIS WORKS is pleased to announce the release of DocFlex/Javadoc version 1.5 with the full support of all new Java 5 language features!

About DocFlex/Javadoc

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

Each doclet is programmed in the form of a template (or a set of templates) using a high quality graphic Template Designer included in the package. Further, the template (or the main template if there are several ones) is passed as an argument to a special interpreter, which, at the same time, serves the role of an ordinary Javadoc doclet (so that it should be specified on the Javadoc command line using -doclet option).

The template interpreter, which is called “DocFlex Doclet”, is the second major part of the DocFlex/Javadoc software. Once launched by Javadoc, the DocFlex Doclet connects to the Doclet API and by interpreting the instructions contained in the specified template generates the output documentation. In that way, each pair {DocFlex Doclet + template set} behaves as a unique full-blown 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:

(At that, the standard template set is very compact. Currently, it consists of only 15 templates occupying just 339 KB of the total file size!)

The output format is specified as another DocFlex Doclet's argument (along with the main template). The following output formats are supported now:

The plain text output can be used for various utilizations of Java code information provided by the Doclet API (for instance, to generate XML files by it, or SQL files to import into a database).

The following screenshots show a framed HTML (left) and pages of RTF (right) demo documentation generated with the standard templates (click to enlarge):

Framed HTML demo
RTF demo, p1 RTF demo, p2 RTF demo, p3

Doclet GUI

Besides accepting the main template and the output format as arguments, the DocFlex Doclet is actually controlled by a lot more other settings. Some of them are the additional options of the selected output format. Others are the parameters of the given template. (Since all the content of the generated documentation is programmed entirely within templates, most of the settings that normally control an ordinary doclet now simply become the template parameters).

All of those settings can be specified as options on the Javadoc command line. In addition, DocFlex Doclet provides a more user-friendly way of specifying everything using a little GUI. The following screenshots show some dialogs of that GUI (click to enlarge):

Doclet Dialog
Generating Output
RTF Option Inspector
Template Parameter Inspector

What are templates?

The DocFlex/Javadoc templates are actually programs. The idea behind such an 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 like this:

  1. First, we need to construct 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. (The interpreter can be started just be calling some member method of the root object representing the controlling structure, e.g. dlg.show())
  3. Finally, the interpreter interprets that controlling structure and produces from the data source some output we need.
What all the programming when using such a library is about is the first step. We should just encode the creation of that controlling structure!

Now, imagine that such a controlling structure is serialized to a file. What is that file then? One may call it a "template"!

But if that is a template, why not to create/edit it using some designer GUI (rather than creating it with the methods of some Java classes)? This way has a number of advantages:

DocFlex/Javadoc is just an implementation of that idea.

The following screenshot show the class.tpl template (which is included in the standard template set and generates the bulk of documentation) open in the Template Designer (click to enlarge):

“class.tpl” template

What is new in version 1.5?

Links

This original article can be found at:
http://www.filigris.com/ann/docflex_javadoc_v1.5/

DocFlex/Javadoc home page:
http://www.filigris.com/products/docflex_javadoc/

Free downloads:
http://www.filigris.com/downloads/