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/
In this article you can read:
<ul><li>About DocFlex/Javadoc</li>
<li>Main Features</li>
<li>System Requirements</li>
<li>Simultaneous Support of Java 1.4 and Java 5</li>
<li>What are Templates?</li>
<li>Standard Template Set</li>
<li>Doclet GUI</li>
<li>Links</li>
</ul>
h2. 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, that 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:
<ul><li>A framed hypertext HTML documentation very similar to that generated by the Standard Javadoc Doclet.</li>
<li>The same documentation in the form of a single HTML file.</li>
<li>The best quality RTF documentation ready for MS Word and OpenOffice.org under Linux</li>
</ul>
The following is a framed HTML demo documentation generated with the standard templates:
http://www.filigris.com/products/docflex_javadoc/examples/html/
h3. Main Features
<ul><li>Full support of new
Java 5.0 language features:
<ul><li>
Generic Types</li>
<li>
Enums</li>
<li>
Annotations</li>
</ul>
</li>
<li>Simultaneous support of Java 1.4 and Java 5 (see below).</li>
<li>The
standard template set included in the software allows instant generation of
<ul><li>Framed HTML JavaDoc similar to that generated by the standard Javadoc doclet.</li>
<li>The same documentation packed into a single HTML file.</li>
<li>The exceptional quality RTF JavaDoc with the correct rendering of HTML tags embedded in Java comments (including insertion of images specified with <img> tags) </li>
</ul>
</li>
<li>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).</li>
<li>A high quality graphic
Template Designer allows visual designing of most of things which development is possible otherwise only by direct Java coding.</li>
<li>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 Mode (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).</li>
<li>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.</li>
<li>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.</li>
<li>The current version of DocFlex Doclet generates output in the following formats:
<ul><li>
HTML (version 4.0)</li>
<li>
RTF (version 1.6 - supported since Word 2000)</li>
<li>
TXT (plain text)</li>
</ul>
</li>
<li>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).</li>
<li>DocFlex/Javadoc supports numerous sophisticated formatting techniques which include
<ul><li>
text formatting: fonts, colors, borders</li>
<li>
paragraph formatting: margins, pagination control, borders, colors</li>
<li>
border formatting: styles (solid, double, dashed, dotted), thickness, colors</li>
<li>
tables: arbitrary cell layouts, borders, nested tables</li>
<li>
lists: bulleted, numbered, delimited</li>
<li>
document fields (RTF): page number, number of pages, TOC, etc.</li>
<li>
page formatting: size, orientation, margins, headers/footers</li>
<li>
formatting styles</li>
<li>
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.</li>
</ul>
</li>
<li>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.</li>
<li>Depending on a particular template, the generated output can be
<ul><li>
single-file document (all formats)</li>
<li>
framed multi-file documentation (HTML only)</li>
</ul>
</li>
<li>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.</li>
<li>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).</li>
<li>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. </li>
</ul>
h2. System Requirements
DocFlex/Javadoc requires the Javadoc Tool delivered with one of the following Java Development Kits:
<ul><li>JDK 6</li>
<li>JDK 5.0</li>
<li>Java2 SDK 1.4 </li>
</ul>
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.
h2. 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!
h2. 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:
<ol><li>First, we need to create a certain object representation of some controlling structure
(using special classes and methods of that library).</li>
<li>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 be 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()).</li>
<li>Finally, the interpreter processes that controlling structure and produces from the data source some useful output (or shows a GUI). </li>
</ol>
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:
<ul><li>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.</li>
<li>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.</li>
<li>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!</li>
<li>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.</li>
<li>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. </li>
</ul>
DocFlex/Javadoc is exactly an implementation of that idea!
The following screenshot shows the
class.tpl template open in the Template Designer:
http://www.filigris.com/ann/docflex_javadoc_v1.5.3/designer.png
This template is included in the standard template set and generates the bulk of the documentation.
h2. 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:
http://www.filigris.com/products/docflex_javadoc/examples/html/
Everything you see in that documentation has been programmed entirely in the templates!
Currently, the standard template set consists of only 15 templates file (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.
h2. Doclet GUI
A doclet implemented as { DocFlex Doclet + template set } is controlled by lots of settings, which include:
<ul><li>The main template</li>
<li>The template parameters</li>
<li>The output format</li>
<li>The format-specific options to the output generator</li>
<li>The output destination (directory/file) </li>
</ul>
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:
http://www.filigris.com/ann/docflex_javadoc_v1.5.3/doclet_dialog.png
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:
http://www.filigris.com/ann/docflex_javadoc_v1.5.3/param_inspector.png
http://www.filigris.com/ann/docflex_javadoc_v1.5.3/rtf_option_inspector.png
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:
http://www.filigris.com/ann/docflex_javadoc_v1.5.3/generating.png
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!
h2. Links
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/