Leonid has posted 3 posts at DZone. View Full User Profile

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

03.09.2012
| 2217 views |
  • submit to reddit
Location: 
http://www.filigris.com/products/docflex_javadoc/

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.

Contents

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

Key Features

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

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

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

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.

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

Integrations

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:

Apache Ant
Apache Maven
Eclipse

Sample Ant buildfile and Maven POM file are included in the distributed software archive.

JavadocPro Template Set

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

            

This everything is complemented with a possibility to filter classes and members by tags/annotations. You can identify classes and members to be documented both:

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

Combined Screenshot

Editions

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:

    1. DocFlex Doclet
    2. JavadocPro Template Set
    3. Basic 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.

    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

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.

About DocFlex

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.

Key Concepts

It is based on four generalizations:

  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/Javadoc is not the only application of DocFlex technology. Currently, there are a few others:

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

0
Published at DZone with permission of its author, Leonid Rudy.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)