DocFlex/Javadoc

  1. What is DocFlex/Javadoc?
  2. Key Features
  3. System Requirements
  4. Editions
  5. How it works
  6. Future Development

1.  What is 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 complexity and quality are equal or exceed the standard Javadoc.

2.  Key Features

Template-driven doclet architecture

Data processing

Hypertext

Output formats

Doclet GUI

Supplied Templates

Integrations

3.  System Requirements

DocFlex/Javadoc requires the Javadoc Tool delivered with one of the following Java Development Kits (JDK) or their equivalents: (JDK 7 may be preferable as it is the fastest!)

Note: Javadoc is not a separate software but rather a part of the whole Java Development Kit (JDK), which you can freely download from the Oracle Corporation website by this link: http://www.oracle.com/technetwork/java/javase/downloads/

Since DocFlex/Javadoc is a pure Java application (the Template Designer GUI is based entirely on Swing), it is supposed to work on any operating system with the installed JDK.

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 successfully on Mac OS X.

Additionally, a sample Ant buildfile and Maven POM file are provided to demonstrate integration of DocFlex Doclet both with Apache Ant and Maven (see also Documentation | Integrations).

For further details, please see product README files on the downloads page.

4.  Editions

DocFlex/Javadoc comes in two editions:
  1. DocFlex/Javadoc - Full Edition
  2. DocFlex/Doclet - Reduced Free Edition
You can freely download both editions from the Downloads page.

Full Edition

The full edition, called “DocFlex/Javadoc” as it is, includes all features available in this product line:
  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, depending on which it may work in one of three modes: The differences between those modes are shown in the table:

Feature / Functionality

Limited Mode

Full Mode

Trial Mode

License type(s) Limited Free License (activated by default) Commercial License Trial License
Template Designer demo only
Possibility to create/modify templates
Execution of any custom templates.

Note: If your custom templates are derived from a template set provided by Filigris Works, their execution will depend also on your license for that template application (see Licensing of Templates).
only those created or modified the last time under a Commercial License distorted output
Execution of Basic Template Set
distorted output
reduced functionality distorted output
DocFlex Doclet (including Doclet GUI)
Generation of HTML, RTF, TXT (plain-text) output
No limitation on input Java project (number of classes etc.)
Any number of output files of any size
Possible usage of generated documentation
any usage unlimited for evaluation only

DocFlex/Doclet

This is a reduced DocFlex/Javadoc without the Template Designer. It includes:
  1. DocFlex Doclet
  2. Basic Template Set
  3. JavadocPro Template Set
DocFlex/Doclet is covered by the Free License. What exactly it allows is shown in this table:

Feature / Functionality

Availability

License type Free License
Possibility to create/modify templates
Execution of custom templates.

Note: If your custom templates are derived from a template set provided by Filigris Works, their execution will depend also on your license for that template application (see Licensing of Templates).
only those created or modified the last time under a Commercial License for “DocFlex/Javadoc”
Execution of Basic Template Set
reduced functionality
DocFlex Doclet (including Doclet GUI)
Generation of HTML, RTF, TXT (plain-text) output
No limitation on input Java project (number of classes etc.)
Any number of output files of any size
Possible usage of generated documentation
any usage

5.  How it works

Here is a UML implementation diagram, which depicts the functional structure of DocFlex/Javadoc:

Main Components

The DocFlex/Javadoc implementation consists of four main components:
  1. The Doclet DSM Driver, which represents a bridge between Javadoc Doclet API and DocFlex core. The driver connects to Javadoc using Doclet API and supplies data via DSM (Data Source Model) interface that is a representation of Javadoc data source in the form understandable for DocFlex core. This representation is called Doclet DSM. The driver also supports DSM Type interface which provides the data structure and type information about this data source. The DSM interface is used by DocFlex Generator to obtain data it operates. The DSM Type interface is used both by the generator to know how to handle those data, and by the Template Designer to provide the data type information during designing of the templates.
  2. The DocFlex Doclet component provides com.docflex.javadoc.Doclet class, which is the one to be specified with the -doclet option on the Javadoc command line. The DocFlex Doclet component processes the command line options received from the Javadoc, initiates the Doclet DSM Driver and starts the generator. It also may invoke the Doclet GUI, which provides a user-friendly interface to specify most of parameters and settings used by the generator.

    For further details, please see: Documentation | DocFlex Doclet

  3. The DocFlex Generator, which is launched by DocFlex Doclet and receives from it: The generator executes the template and generates the output documentation.
  4. The Template Designer, which provides a GUI for designing the templates. It also starts Doclet DSM Driver (however, without connection to Javadoc) and uses information provided by DSM Type interface. In the next section, we shall discuss what that information is.

Doclet DSM

When Javadoc is started, first, it collects the information about the Java sources to be documented. Javadoc does this by parsing all the Java classes (most likely, it just calls from itself the Java compiler that does that parsing job).

Once the collecting of the information is finished, Javadoc calls a doclet (by default, the Standard Doclet) and passes to it all the Java source information organized in the form of a tree-like representation, which is provided to the doclet via the Doclet API.

One may notice, however, that the structure of that representation is very much similar to that described by DOM (the Document Object Model of an XML file). All data provided by Doclet API can be represented either as some XML elements or as their attributes.

DocFlex/Javadoc makes use of this. It maps all the Doclet API classes (such as com.sun.javadoc.ClassDoc) to the equally named elements and the values returned by the methods of those classes -- to the element's children and attributes (see below).

As a result, the entire Doclet API is mapped on some XML-like representation called Doclet Data Source Model (or Doclet DSM). The elements and attributes, on which everything is mapped, are called DSM elements and DSM attributes.

Actually, that XML-like representation is not created in memory. Rather, it is maintained dynamically by the Doclet DSM Driver. When a particular element or attribute is needed, the driver just calls the corresponding method of a Doclet API class.

The methods of Doclet API classes (or more precisely, the data they return) are mapped according to the following rules:

You can see all mapping of Doclet API to XML used by Doclet DSM, if you look at FlexQuery Assistance Dialog invoked from the Template Designer. Here is a screenshot of it (click to see a larger screenshot):
Doclet API Data Source Model
In effect, the tree visible on this picture represents all the Doclet API in a very simple but equally powerful form.

How fast it works

Even though the entire JavaDoc Generator is implemented as a set of templates, which adds an additional level of interpretation, we have passed a very long way of optimizations.

Now, by its performance, the result doclet (i.e. DocFlex Doclet + templates) may well rival with anything written directly in Java!

Here are a couple of tests that have been run on Java SE 6u3 JDK Source Code (downloaded from: http://java.sun.com/javase/downloads/) using JavadocPro templates and default generator settings.

Generation of Framed HTML Documentation

The following is the result of the generation of a framed HTML documentation by all Java sources of the following packages (with all subpackages): which is essentially identical to the entire Java SE 6 API Specification.

Number of packages/classes:   196 / 3558
Total source code size:   40.8 Mb (all files)
Generation time (1):   637 sec (Windows XP 32-bit)
Generation time (2):   449 sec (Windows 7 64-bit)
Result HTML documentation:   187 Mb
Number of generated files:   8491
Template Set:   JavadocPro
DocFlex/Javadoc version:   1.6.0
JDK version:   1.7.0 (32-bit / 64-bit)
Computer platform:   Intel Core 2 Duo E6600, 4GB RAM

Generation of RTF Documentation

The following is the result of the generation of a single-file RTF documentation by the Java sources of javax.swing package and subpackages:

Number of packages/classes:   17 / 633
Total source code size:   10.8 Mb (all files)
Generation time:   93 sec
Result RTF document:   22.5 Mb (with images)
Number of pages (A4):   3516
Template Set:   JavadocPro
DocFlex/Javadoc version:   1.6.0
JDK version:   1.7.0 (Windows XP 32-bit)
Computer platform:   Intel Core 2 Duo E6600, 4GB RAM

6.  Future Development

For the next major versions we plan to develop some really serious new things:
  1. First of all, we are going to support a new major output format. Most likely, this will be the direct generation of DITA output.

    Currently, you can generate DITA output too using specifically designed templates and plain text output (see Key Features | Output formats | TXT | Generation of XML), but any formatting specified as properties of template components (e.g. fonts, colors, tables etc.) won't be rendered in that case.

    If you have more questions on this topic, please write us to contact@filigris.com

  2. Improvements of Template Designer, such as
  3. Self-documenting templates (i.e. a set of templates to document any other DocFlex templates).
  4. Finally, we always keep in mind that there is such a thing called Eclipse, where the whole our technology (in particular, the Template Designer) eventually is going to be.

    Integration of the DocFlex Doclet with Eclipse was possible from the very start. See Documentation | Integrations | Eclipse

If you are interested in any other features to be supported, please do not hesitate to send us your feature request to: support@docflex.com. We are always happy to hear your opinion, no matter whether you are registered DocFlex/Javadoc user or not!

Moreover, depending of what feature you need, we will try to figure out how to implement this right now. So, it's quite possible you could see your feature just in a few days within the next minor update!


Copyright© 2017 Filigris Works. Leonid Rudy Softwareprodukte. All rights reserved.
To contact us, please visit www.filigris.com or e-mail to: contact@filigris.com