DocFlex/Javadoc 1.5.6, multi-format doclet and rapid doclet development tool
DocFlex/Javadoc
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.
Key Features
- Template-driven doclet architecture
-
Actual doclets are created in the form of special
templates interpreted by the DocFlex Doclet, which is
the template interpreter / output generator wrapped in the form of a
Javadoc Doclet.
-
The high quality graphic Template Designer
allows you to visually design most of things, whose development was possible so far only
by direct Java coding.
-
The templates are designed independently on a particular output format.
All formatting is specified in some universal way using properties of template components.
During the generation, it is rendered with the suitable features available in the selected output format.
-
The elaborated support of template parameters (including multivalued list parameters).
The parameters are defined and accessed within templates to adjust
dynamic properties of template components.
Most of options previously used to control an ordinary doclet now simply become template parameters!
-
The possibility to call templates from one another.
This feature (along with the template parameters) makes possible re-using the same templates
for different tasks as well as organizing template libraries.
- Data processing
-
The entire Doclet API is represented in the form of a virtual XML document
(called Doclet DSM), on which the designing and processing of all templates is based.
-
Sophisticated capabilities for data querying and sorting
based on an extension of XPath.
-
Full support of new Java 5.0 language features:
Generic Types, Enums, Annotations.
-
Simultaneous support of Java 1.4 and Java 5.
- Creating hyperlinks
-
Generation of an extensive network of hyperlinks interconnecting the whole documentation.
-
The hyperlinks can be generated in all output formats that support them (this currently includes HTML and RTF).
-
The universal way of defining documentation cross-links based on the link/target keys specified in templates.
-
In RTF, the cross-links can be generated in the form of page number references,
which effectively makes them usable even in the printed documentation.
-
In HTML, the possibility of loading several frame windows from a single hyperlink at once.
- Universal support of various formatting techniques
- 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 text data (e.g. documentation comments). Almost all HTML tags practically
usable in doc-comments are supported.
- Inserting images
- statically specified in templates
- dynamically, obtained by
<img>
tags found in Java comments
- supported image formats: GIF, PNG, JPG, WMF, EMF, BMP
- Output formats
-
HTML (both framed multi-file and single-file output)
-
RTF (version 1.6 - supported since Word 2000).
-
TXT (plain text), which may be particularly useful for various utilizations
of the Java code information provided by the Doclet API
generate XML files by it, or SQL files to import into a database).
- Standard Template Set
-
The ready-to-use Standard Template Set
included in all editions of DocFlex/Javadoc allows you
to immediately generate:
-
The framed HTML Java API documentation similar to that generated by the standard Javadoc.
-
The same documentation packed in a single HTML file.
-
The unmatched quality RTF JavaDoc.
-
Special features supported by standard templates:
-
Excluding classes/methods/fields by custom tags and annotations.
-
Selective omitting of package qualifiers.
-
Selective documenting of custom tags (similar to
-tag
option of Standard Doclet).
-
By modifying the standard templates,
you can quickly customize the generated documentation according to your needs.
- Doclet GUI
-
Besides command line options, DocFlex Doclet supports an alternative user-friendly way
to control the template-based doclets interactively -- the high quality Doclet GUI.
-
The Doclet GUI starts with the Generator Dialog,
where you can specify all general settings (such as the main template, the output format and
the output directory), start the generation, track its progress and stop at any moment you need.
-
The grid-tree-based Parameter Inspector
invoked from the Generator Dialog
for a selected template allows you to view the descriptions of all template parameters controlling
the doclet and set their values according to the parameter data types.
-
The generator options specific for the selected output format can be set in the
corresponding Format Option Inspector
(also invoked from the Generator Dialog).
-
Once the generation is finished (or cancelled), you can start it again
with different settings or a new main template without restarting the whole Javadoc.
- Integrations
-
With any system that runs Javadoc (in particular, see below)
-
Apache Ant
-
Apache Maven 2
-
Eclipse
For lots more information, see DocFlex/Javadoc homepage:
http://www.filigris.com/products/docflex_javadoc/
Availability
DocFlex/Javadoc comes in two editions:
-
The full edition called “DocFlex/Javadoc” as it is.
This is commercial software, which includes all the implemented functionality.
-
The reduced freeware edition called “DocFlex/Doclet”.
It includes only the output generator and can be used as an interpretor
of any custom templates.
It also includes the standard template set, which allows you to instantly use it
as an HTML doclet (similar to the standard one, however with some special features)
plus an excellent quality RTF doclet.
Both editions are available for downloads on the page:
http://www.filigris.com/downloads/
This Version
New features:
-
The template interpretor works 15-20% faster
-
Improvement of RTF output
-
Multi-valued (list) template parameters
-
Custom elements
-
Standard Templates: Selective documenting of custom tags (similar to
-tag
option of standard doclet)
For more details, see product Readme | Change Log on the downloads page:
http://www.filigris.com/downloads/
What is DocFlex?
DocFlex is an innovative technology for development of high quality template-driven
documentation/report generators by any kind of data obtained from various software
applications via the Java APIs they provide.
Main Concepts
The whole DocFlex technology is based on four generalizations:
-
The mapping of an entire Java API onto a virtual XML-like representation
made of some elements and attributes so as to process any such a representation in a universal way
using techniques borrowed from the field of XML, like XPath (or more precisely, a conceptual
analogue of XPath with some extensions not present in it).
-
The abstract formatting concept based on four layouts (flow of text, flow of paragraphs or paragraph-like objects,
tables and lists), which can be rendered in most modern document formats (e.g. HTML, RTF, XSL-FO etc.)
-
The automatic generation of hyperlinks (or their page number reference equivalents)
by matching the sets of keys produced from certain natural properties
of the things (entities) being documented and hyper-linked.
-
The representation of the object controlling structure of the output generator (made on the first three principles)
in the form of a plain-text template with a possibility to create and edit such templates using a graphic
Template Designer, which visualizes the controlling objects (now becoming template components)
in a form resembling the output they will produce.
The following screenshot shows the class.tpl
template open in the Template Designer.
That template belongs to the standard template set provided with DocFlex/Javadoc,
where it generates the bulk of the Java API documentation.
Click to see a real-size (more expanded) screenshot:
Other Applications
In fact, DocFlex/Javadoc is not the only application of DocFlex technology.
The following is a summary of other DocFlex software:
DocFlex/XML
The SDK and runtime environment for rapid development and execution
of template-driven automatic documentation/report generators by any data obtained from XML files.
This is currently the most complex and advanced application of DocFlex technology.
Actually, this tool can be considered a powerful alternative to XSLT.
At least, it is definitely able to do what XSLT apparently not (for example, see “XSDDoc” below).
We will publish a more detailed comparison “DocFlex/XML vs. XSLT” with the next DocFlex/XML release,
which is coming very soon.
DocFlex/XML home page:
http://www.filigris.com/products/docflex_xml/
DocFlex/XML | XSDDoc
A template set for DocFlex/XML that implements a high quality
W3C XML Schema documentation generator in HTML and RTF output formats.
For more details, please see:
http://www.filigris.com/products/docflex_xml/xsddoc/
DocFlex/XML | WSDLDoc
A similar template set for DocFlex/XML that will implement a high-end WSDL documentation generator.
This product is not released yet.
DocFlex/Together
A template-driven documentation generator for
Borland Together
(which is a UML modelling tool).
This is the earliest application of DocFlex technology and probably the most beautiful one.
It works only with Together Architect 1.x, which is now obsolete.
Unfortunately, since Together 2005, Borland eliminated any open APIs (for unknown reasons).
Because of this, further development of DocFlex/Together was impossible.
DocFlex/Together home page:
http://www.filigris.com/products/docflex_together/
See also examples of the UML documentation generated with it:
http://www.filigris.com/products/docflex_together/examples/
The future DocFlex/UML is going to generate something like this as well.
DocFlex/UML
A template-driven UML documentation generator based on
Eclipse EMF.
This tool is in early development stage yet. In a sense, it will continue DocFlex/Together
with the focus on integration with other UML tools that use Eclipse EMF.
Links
This original article can be found at:
http://www.filigris.com/ann/docflex_javadoc_v1.5.6/
DocFlex/Javadoc home page:
http://www.filigris.com/products/docflex_javadoc/
DocFlex/XML home page:
http://www.filigris.com/products/docflex_xml/
DocFlex/XML | XSDDoc, the XML schema documentation generator:
http://www.filigris.com/products/docflex_xml/xsddoc/
Free downloads:
http://www.filigris.com/downloads/