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:
http://www.filigris.com/products/docflex_javadoc/
Also, read in this article:
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:
- A framed hypertext HTML documentation very similar to that generated by the Standard Javadoc Doclet.
- The same documentation in the form of a single HTML file.
- The best quality RTF documentation ready for MS Word and OpenOffice.org under Linux
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):
These screenshots show pages of the generated demo RTF documentation (click to enlarge):
Main Features
-
Full support of new Java 5.0 language features:
- Generic Types
- Enums
- Annotations
-
Simultaneous support of Java 1.4 and Java 5 (see below).
-
The standard template set included in the software allows instant generation of
- Framed HTML JavaDoc similar to that generated by the standard Javadoc doclet.
- The same documentation packed into a single HTML file.
-
The exceptional quality RTF JavaDoc with the correct rendering of HTML tags embedded in Java comments
(including insertion of images specified with
<img> tags).
Besides this, it is possible to exclude from the result documentation
any mentioning of classes, fields and methods marked with the specified tags or annotations --
a unique capability unknown to us to be supported by any other doclet (including the standard one).
-
A high quality graphic Template Designer
allows visual designing of most of things which development is possible otherwise
only by direct Java coding.
-
The Template Designer represents the whole Doclet API in the form similar to XML DOM,
which is a kind of a virtual XML document called Doclet Data Source Model (or Doclet DSM).
This makes possible programming and processing of the data provided by the Doclet API using universal
approaches developed for XML (such as XPath).
-
The templates created with the Template Designer are interpreted by the
DocFlex Doclet, an output generator implemented as a Javadoc doclet
and included in the package. In effect, the templates interpreted
by the DocFlex Doclet behave as if they are separate doclets themselves.
-
Besides the possibility to specify all doclet setting using
options on the Javadoc command line, DocFlex Doclet
also provides a high quality Doclet GUI,
where you can assign the same settings at once in a lot more user-friendly way,
start the generation, track its progress and cancel it at any moment (if you wish).
Once the generation has been finished (or cancelled), you can start it again
with different settings and a new (or modified) template set.
This, in effect, allows changing your doclet on the fly.
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.
-
The current version of DocFlex Doclet generates output in the following formats:
- HTML (version 4.0)
- RTF (version 1.6 - supported since Word 2000)
- TXT (plain text)
The plain text output may be particularly useful 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).
-
DocFlex/Javadoc supports numerous sophisticated formatting techniques which include
- text formatting: fonts, colors, borders
- paragraph formatting: margins, pagination control, borders, colors
- border formatting: styles (solid, double, dashed, dotted), thickness, colors
- tables: arbitrary cell layouts, borders, nested tables
- lists: bulleted, numbered, delimited
- document fields (RTF): page number, number of pages, TOC, etc.
- page formatting: size, orientation, margins, headers/footers
- formatting styles
-
rendering of embedded HTML, which means interpreting in non-HTML output formats (such as RTF)
the HTML tags embedded in Java source comments. Almost all HTML tags practically usable
in doc-comments are supported now.
-
The templates can be designed independently on a particular output format, which is selected only
when starting the generation. All formatting specified in templates is defined in some universal way
(using properties of template components) and, then, rendered with the suitable features
available in the selected output format.
-
Depending on a particular template, the generated output can be
- single-file document (all formats)
- framed multi-file documentation (HTML only)
-
The framed documentation is generated using special frameset templates.
Each frameset template, among other things, contain a frameset definition
that allows defining your own layout of frame windows and target
the documents loaded by hyperlinks into particular frames.
-
DocFlex/Javadoc is able to generate a common network of hyperlinks
for the whole documentation.
The generation of hyperlinks is programmed using special source- and target-keys
defined in the template components. It is also possible to program loading
several frame windows from a single hyperlink at once.
The hyperlinks can be generated in all output formats that support them
(currently, this includes HTML and RTF).
-
Since all content and formatting of the generated documentation now is specified in templates,
the most of options previously used to control behavior of an ordinary doclet now simply become
template parameters.
DocFlex/Javadoc provides elaborated support for template parameters.
The parameters can be defined and accessed within templates to adjust
the dynamic properties of template components.
The values of template parameters can be specified both on the Javadoc command line and
interactively using a special Parameter Inspector dialog invoked from the
Doclet GUI provided by the DocFlex Doclet.
System Requirements
DocFlex/Javadoc requires the Javadoc Tool delivered with one of the following Java Development Kits:
- JDK 6
- JDK 5.0
- Java2 SDK 1.4
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!
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:
-
First, we need to create a certain object representation of some controlling structure
(using special classes and methods of that library).
-
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
dlg.show()).
-
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:
-
A designer GUI can visualize everything.
Now, rather than coding abstract method calls, we can visually construct the controlling structure
using the notions of things that we expect to see in the generated output.
-
Since probably every modern document format in its core is based on the same obvious concepts
like flows of text with specified fonts and colors, paragraphs with specified margins, borders and
other properties, tables, bulleted/numbered lists, images and so on, most of such things can
be defined in some universal format-independent way, which can be encoded in the form of template components.
-
Such template components can be visualized in the template designer GUI. This allows easy
manipulation with them (creating/defining, modifying, moving, coping and so on).
Doing the same by calling various Java methods and modifying Java code each time we need
to change something would be a lot more cumbersome!
-
On other hand, the template interpreter will render those template components
with the suitable features of the particular destination output format (such as HTML or RTF).
So, we can be relieved from learning and programming lots of very complicated
(and sometimes poorly documented) things specific to a particular format.
Instead, we can more concentrate on our primary application task.
-
The template designer (to a large degree) ensures that the result controlling structure
(the template) is valid. That is, it won't hang when interpreted and will produce some output anyway.
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):
This template is included in the standard template set and generates the bulk of the documentation.
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):
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
http://download.java.net/jdk6/ -> 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.
A doclet implemented as {DocFlex Doclet + template set} is controlled by lots of
settings, which include:
- The main template
- The template parameters
- The output format
- The format-specific options to the output generator
- The output destination (directory/file)
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):
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):
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):
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:
http://www.filigris.com/ann/docflex_javadoc_v1.5.3/
DocFlex/Javadoc home page:
http://www.filigris.com/products/docflex_javadoc/
Free downloads:
http://www.filigris.com/downloads/
