DocFlex/Javadoc 1.6.0: Multi-Format Doclet & Doclet Development Tool

• About DocFlex/Javadoc
  • Template-Driven Doclet Architecture
  • Data Processing Model
  • Output Formats
  • Doclet GUI
  • System Requirements
  • Integrations
  • Supplied Templates
• JavadocPro Template Set
  • What you can generate with it
    • Framed HTML (Classic JavaDoc)
    • Single File HTML
    • RTF Documentation
  • Filtering of classes/members by tags/annotations
  • More than 70 parameters to customize your JavaDoc
    • Specifying parameters via Standard Doclet options
• Combined Screenshot
• DocFlex/Javadoc Editions
  • Full Edition
  • DocFlex/Doclet
• Benefits of DocFlex/Javadoc
• About DocFlex
  • Key Concepts
  • Other Applications
    • DocFlex/XML
    • DocFlex/XSD
    • DocFlex/WSDL
• Links

About DocFlex/Javadoc

Template-Driven Doclet Architecture

• 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 -- 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):

  

• Universal support of various formatting techniques

  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.

  The following formatting techniques are supported:

  • 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 of images
  • statically specified in templates
  • dynamically, obtained by <img> tags found in Java comments
  • supported image formats: GIF, PNG, JPG, WMF, EMF, BMP
• Hypertext
  • 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.
  • In HTML, it is possibile to load several frame windows from a single hyperlink at once.
• Template Parameters

  Since all the content and formatting of the generated JavaDoc is programmed entirely in templates, what previously were command-line options provided by the Standard Doclet now simply become template parameters. The parameters are defined and accessed within templates to adjust dynamic properties of template components.

• Template Libraries

  The templates can be called from one another, which (along with the template parameters) allows reusing the same templates for different tasks and even in different doc-generators.

Data Processing Model

• Doclet API as virtual XML document

  The entire Doclet API is represented in the form of a 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.

• Location Paths / Location Rules / Element Maps

  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.

• Java 5.0 language features

  Full support of all new Java 5.0 language features: Generic Types, Enums, Annotations.

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)

  See also: JavadocPro Template Set | What you can generate with it

• 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).

  Generation of XML

  Since XML files are just text files, you can easily generate any sorts of XML output from the data provided by Doclet API using DocFlex/Javadoc.

  To generated XML, all you need is to design a template where the output produced by Data Controls (from the data obtained from Doclet API) is interchanged with the static text representing certain XML tags, which can be produced, for instance, by Text Controls. Then, you can simply generate a TXT output with such a template, and this will be XML.

Doclet GUI

• The main template
• The template parameters
• The output format
• The format-specific options to the output generator
• The output destination (directory/file)

So, besides command line options, DocFlex Doclet provides a more user-friendly way to control the template-based doclets interactively -- the Doclet GUI:

• Generator Dialog

  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 Generator Dialog (click to enlarge):

  

  Here, you can fill in all required 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.

• Template Parameter / Output Format Option Inspectors

  The additional settings, such as template parameters and output format options can be assigned in the special property inspector dialogs invoked by clicking the buttons on the right (click to enlarge):

  Here you can edit the parameter or option values according to their data types. The bottom panel in the inspector dialog shows the HTML-preformatted description of each parameter or format-specific generator option.

• Generating: start, see progress, stop / restart again

  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!

System Requirements

• JDK 7
• JDK 6
• JDK 5.0
• Java2 SDK 1.4

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. We have been also reported that DocFlex/Javadoc worked well on Mac OS X.

Integrations

We have worked out and tested the integrations with the following systems:

• Apache Ant
• Apache Maven
• Eclipse

Supplied Templates

1. Basic Template Set

   This is an early version of standard templates provided before DocFlex/Javadoc v1.6.0. It is able to generate both HTML (framed/single file) and RTF JavaDoc for any Java projects, however, this will include only basic content: project overview, package summaries, class details. All Java 5 language features are fully supported.

2. JavadocPro

   See: JavadocPro Template Set

JavadocPro Template Set

• Framed HTML JavaDoc identical to the classic one.
• Single-file HTML JavaDoc with basic content (project overview, package summaries, class details)
• The newly redesigned RTF JavaDoc (which can be further converted to PDF).

JavadocPro template set home page: http://www.filigris.com/products/docflex_javadoc/templates/JavadocPro/

What you can generate with it

• Framed HTML (Classic JavaDoc)

  Using FramedDoc.tpl main template, you can generate a complete JavaDoc identical to the classic one (click on a screenshot to view a demo HTML JavaDoc):

  The following functionality is fully supported:

  • Generation of file/page types:
    • Basic Content Pages
      • overview-summary.html
      • package-summary.html
      • classname.html
    • Cross-Reference Pages
      • all-classes-summary.html
      • overview-tree.html
      • package-tree.html
      • package-use.html
      • class-use/classname.html
      • deprecated-list.html
      • constant-values.html
      • serialized-form.html
      • index-all.html
      • index-files/index-n.html (index by letter)
    • Support Files
      • help-doc.html
      • index.html
      • overview-frame.tpl
      • all-classes-frame.tpl
      • package-frame.tpl
      • package-list
  • Standard Javadoc navigation bar
  • Switching between FRAMES / NO FRAMES views
• Single File HTML

  The same entire documentation can be equally generated as a single HTML file using PlainDoc.tpl main template.

  

• RTF Documentation

  Using PlainDoc.tpl main template, it is possible not only to generate a single file HTML. Simply, by switch the generator output format to “RTF”, the same template will produce a highest quality RTF file!

  This includes:

  • Processing of HTML tags in Java comments. HTML markup will be rendered with appropriate RTF formatting.
  • Insertion of images (via <img> HTML tags).
  • Page headers/footers relevant to the page content.
  • Page number references in summary table (which substitute for hyperlinks).
  • Generation of Table Of Contents.

  These screenshots show pages of an RTF documentation generated by several JDK Source classes (click to see in full size):

Filtering of classes/members by tags/annotations

• Explicitly -- those that are marked with including tags/annotations
• Implicitly -- those that are not marked with the excluding tags/annotations

This takes into account the following effects:

• Inheriting members of excluded classes
• Shadowing of equally named fields
• Dynamic extension of type variables

More than 70 parameters to customize your JavaDoc

Specifying parameters via Standard Doclet options

Combined Screenshot

DocFlex/Javadoc 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. Basic Template Set - an early version of standard template set.
  4. 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.

  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:

  1. DocFlex Doclet
  2. Basic Template Set
  3. JavadocPro Template Set

  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.

  JavadocPro will work in limited mode. However, that will be enough to generate full-blown framed HTML JavaDoc with the same functionality as provided by the standard Javadoc. All template parameters equivalent to Standard Doclet options will be unlocked.

  If you are not a big fan of the 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!

Benefits of DocFlex/Javadoc

• 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. That's because such a feature is pretty much controversial:

  1. It is rather difficult to implement. To make the generated docs consistent, the excluded classes must be not only 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.
  2. It contradicts the very essence of class/member visibility. According to the canonical approach, ins tead 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, the real life 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.

About DocFlex

Key Concepts

1. 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).
2. 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.)
3. 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.
4. 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.

Other Applications

• DocFlex/XML

  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/

• DocFlex/XSD

  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/

• DocFlex/WSDL

  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/

Links

DocFlex/Javadoc examples: http://www.filigris.com/products/docflex_javadoc/examples/

Free downloads: http://www.filigris.com/downloads/

This original article can be found at: http://www.filigris.com/ann/docflex_javadoc_v1.6.0/