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.
Application Modernization: What Is It and How to Get Started
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 are equal or exceed the standard Javadoc.
DocFlex Doclet + Template Sets
Doclet API as virtual XML document
Abstract Formatting Concept
JavadocPro Template Set
Framed HTML (Classic JavaDoc)
Single File HTML
Filtering of classes/members by tags/annotations
Benefits of DocFlex/Javadoc
- DocFlex Doclet + Template Sets
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
- Template Designer
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 -- features that are possible to develop so far only by direct Java coding!
The following screenshot is the JavadocPro | class.tpl template open in the Template Designer (click to see in full size):
- Doclet API as virtual XML document
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 some of the technologies developed around XML for Javadoc.
Most of data mining and retrieval is based on Location Paths / Location Rules, which is a developed extension of XPath. This is complemented with the specifically adapted hash-maps (called element maps) that serve the role of indexes.
- Abstract Formatting Concept
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 also supports 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.
- Output Formats
- 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. 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.
- JavadocPro Template Set
- 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):
You can identify both classes and members to be documented:
- Explicitly -- those that are marked with including tags/annotations
- Implicitly -- those that are not marked with the excluding tags/annotations
It will work for all types of generated documentation equally!
The inclusion/exclusions of classes is controlled and processed separately, which allows you to exclude specific classes from the documentation, while letting some of their public/protected members still be visible. At that, the generated JavaDoc will look as if the excluded classes themselves never existed 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
- Framed HTML JavaDoc identical to classic one (click on a screenshot to view a demo HTML JavaDoc):
DocFlex/Javadoc comes in two editions:
- Full Edition (or “DocFlex/Javadoc” as it is) includes all features available in this software:
- Template Designer - provides a GUI to design/modify templates.
- DocFlex Doclet - the template interpreter / output generator wrapped in the form of a Javadoc Doclet.
- 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.
- Basic Template Set - an early version of standard template set.
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.new JavaDoc design introduced in Java 7, you can use JavadocPro templates to generate the classic-looking JavaDoc under Java 7 too. That's free!
- 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 to ever support it. That's because such a feature is pretty much controversial:
- It is rather difficult to implement. To make the generated docs consistent, the excluded classes must be not only be removed, everything needs to be changed as if those classes never existed at all. For instance, the public members of some excluded classes may still be required to appear in the documentation. But in that case they must be shown as if they are defined in other classes, which actually inherit them.
- It contradicts the very essence of class/member visibility. According to the canonical approach, instead of deriving a public API directly from the implementation, you are supposed, first, to define the entire API in the form of some abstract interfaces and, then, to maintain the actual implementation separately.
Of course, real life does not always follows some canonical schemes!
- 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.
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 as 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 than the following three things:
- DocFlex/XML -- see above.
- DocFlex/XML XSDDoc -- a template set for DocFlex/XML that implements a high quality XML schema documentation generator.
- 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: http://www.filigris.com/products/docflex_javadoc/
DocFlex/Javadoc examples: http://www.filigris.com/products/docflex_javadoc/examples/
Free downloads: http://www.filigris.com/downloads/
An extended version 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