DocFlex/Javadoc 1.6.0: Multi-Format Doclet & Doclet Development Tool
DocFlex/Javadoc is both a multi-format Javadoc Doclet and a programming tool for rapid development of Javadoc-based Java API documentation generators in various output formats, which by their quality and complexity may be equal or exceed the standard Javadoc.
Key Features DocFlex Doclet + Template Sets Template Designer Doclet API as virtual XML document Abstract Formatting Concept Hypertext Output Formats Integrations JavadocPro Template Set Framed HTML (Classic JavaDoc) Single File HTML RTF Documentation Filtering of classes/members by tags/annotations Combined Screenshot Editions Full Edition DocFlex/Doclet Benefits of DocFlex/Javadoc About DocFlex Key Concepts Other Applications DocFlex/XML DocFlex/XSD DocFlex/WSDL Links
Actual doc-generators 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.
See also: About DocFlex
The high quality graphic Template Designer represents the templates in a visual form resembling the output they generate. At the same time, it allows programming of very sophisticated processing of the input data and formatting of the generated output -- the features possible to develop so far only by direct Java coding!
On the following screenshot is the JavadocPro | class.tpl template open in the Template Designer (click to see in full size):
The entire Doclet API is represented in a form of virtual XML document called Doclet DSM (here "DSM" stands for "Data Source Model"), on which the designing and processing of templates is based. This allows using for Javadoc some of the technologies developed around XML.
Most of data mining and retrieval is based on Location Paths / Location Rules, which is a developed by us extension of XPath. This is complemented also with the specifically adapted hash-maps (called element maps) that serve the role of indexes.
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, this is rendered with the appropriate features available in the selected output format.
It is also supported the 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.
- Generation of cross-reference hyperlinks interconnecting the whole documentation. The hyperlinks are defined in templates in a very abstract way using special link/target keys.
- Generation of hyperlinks to any external URLs. This allows, for instance, linking the generated JavaDoc to any other existing javadoc-generated documentation of external referenced classes.
Hyperlinks can be generated in all output formats that support them (this currently includes HTML and RTF). In RTF, the cross-reference links can be represented also in the form of page number references, which in effect makes them usable even in printed documentation.
- HTML (both framed multi-file and single-file HTML output)
- RTF (version 1.6 - supported since Word 2000; can be further converted to PDF)
TXT (plain text)
It may be particularly useful for various utilizations of the Java code information provided by the Doclet API (for instance, to generate XML files by it, or SQL files to import into a database).
As being a Javadoc Doclet (that is a special plug-in for Javadoc), DocFlex Doclet can be integrated with probably anything that runs Javadoc itself. Specifically, we have worked out and tested the integrations with the following systems:
Sample Ant buildfile and Maven POM file are included in the distributed software archive.
Since the version 1.6.0, DocFlex/Javadoc is supplied with a new "JavadocPro" template set. Using it you can generate:
- Framed HTML JavaDoc identical to classic one (click on a screenshot to view a demo HTML JavaDoc):
- Single-file HTML JavaDoc with basic content (project overview, package summaries, class details):
- The newly redesigned RTF JavaDoc (click on a screenshot to see in full size):
• Explicitly -- those that are marked with including tags/annotations
• Implicitly -- those that are not marked with the excluding tags/annotations
The inclusion/exclusions of classes is controlled and processed separately, which allows you to exclude specific classes from the documentation, yet to let some their public/protected members be visible still. At that, the generated JavaDoc will look as if the excluded classes themselves did never exist at all, however, everything else is in place and correct. This takes into account the following effects:
• Inheriting members of excluded classes
• Shadowing of equally named fields
• Dynamic extension of type variables
DocFlex/Javadoc comes in two editions:
Full Edition (or "DocFlex/Javadoc" as it is) includes all features available in this software:
1. Template Designer - provides a GUI to design/modify templates.
2. DocFlex Doclet - the template interpreter / output generator wrapped in the form of a Javadoc Doclet.
3. JavadocPro Template Set - the new advanced template set able to generate classic HTML JavaDoc as well as redesigned RTF documentation with a possibility to exclude classes/members by tags/annotations.
4. Basic Template Set - an early version of standard template set.
This everything is covered by the same “DocFlex/Javadoc” license, which unlocks all implemented functionality.
DocFlex/Doclet is a free edition of DocFlex/Javadoc.
It does not include the Template Designer (that is, you cannot create/modify any templates). What it includes is:
The "DocFlex/Doclet" is covered by the Free License. That means you can use it immediately as soon as you download it. No registration required! The output (JavaDoc) you generate with it is free for any usage.
We suggest the following:
Generation of classic JavaDoc with a possibility to
exclude any classes and members by tags/annotations
The standard Javadoc does not support this and unlikely will ever do.
Generation of outstanding quality RTF JavaDoc
You will hardly find any other tool able to generate such a complex RTF!
Unlimited possibility to customize your Java API documentation
Since all the generated documentation output is programmed entirely in templates (which are open for any changes), now you can:
• Translate all JavaDoc text labels into any other language.
• Change fonts, colors and other look&feel of your JavaDoc.
• Add more filtering conditions for what is included in your JavaDoc.
• Add sections with some special content (not found in the classic JavaDoc).
Program a complete different JavaDoc generator / utilize your Java project info for whatever else
Ultimately, you can program a completely different JavaDoc generator, and even in a different format (particularly XML-based, e.g. DITA) using plain text output. DocFlex/Javadoc can help you also to retrieve whatever information about your Java project (if only provided by Doclet API) so as to utilize it for other purposes -- not only as documentation.
DocFlex is a technology for development of high quality template-driven documentation/report generators from any kind of data provided by various software applications via their standard Java APIs.
It is based on four generalizations:
- The mapping of the entire Java API onto a virtual XML-like representation made of some elements and attributes so as to process it 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 sets of keys produced from certain natural properties of the objects (entities) being documented and hyper-linked.
The representation of the entire object controlling structure of an output generator (made on the first three principles)
in the form of a special plain-text file called template, which can be created and edited using a graphic
template designer that visualizes all the controlling objects (now becoming template components)
in a form resembling the output they produce.
Since the template themselves are not true computer programs, something needs them to interpret. That is called the template interpreter / output generator.
DocFlex/Javadoc is not the only application of DocFlex technology. Currently, there are a few others:
The template-driven documentation/report generator by any data stored in XML files. More precisely, it is a development tool (SDK) and a runtime environment (RE) for such generators, the same like DocFlex/Javadoc is for Javadoc doclets.
DocFlex/XML home page: http://www.filigris.com/products/docflex_xml/
The template-driven documentation generator for W3C XML schemas (XSD files) -- probably, the best in the world!
In fact, it is nothing more but a bunch of three things:
1. DocFlex/XML -- see above.
2. DocFlex/XML XSDDoc -- a template set for DocFlex/XML that implements a high quality XML schema documentation generator.
3. DocFlex/XML XMLSpy Integration -- an integration of DocFlex/XML with Altova XMLSpy®. It allows automatic insertion of XSD diagrams produced by XMLSpy into the XML schema documentation generated by DocFlex/XML XSDDoc. The entire thing (DocFlex/XML + XSDDoc + XMLSpy) works as a single documentation generator. (More similar integrations are coming).
DocFlex/XSD home page: http://www.filigris.com/products/docflex_xsd/
A similarly made WSDL documentation generator, which is in development yet. It is coming in a few months.
Its home page will be here: http://www.filigris.com/products/docflex_wsdl/
DocFlex/Javadoc home page:
DocFlex/Javadoc examples: http://www.filigris.com/products/docflex_javadoc/examples/
Free downloads: http://www.filigris.com/downloads/
An extended variant of this article can be found at: http://www.filigris.com/ann/docflex_javadoc_v1.6.0/
It is also available as zip archive (with all images): http://www.filigris.com/ann/docflex_javadoc_v1.6.0.zip
(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)