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.
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 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:
<img>
tags found in Java commentsSince 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.
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.
The entire Doclet API is represented in a form of virtual XML document (called “Doclet DSM”), 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 XML XPath. This is complemented also with the specifically adapted hash-maps (called “element maps”) that serve the role of indexes.
Full support of all new Java 5.0 language features: Generic Types, Enums, Annotations.
As you perhaps know, since JDK 5.0, the Doclet API has been extended to reflect the new language features introduced in Java 5. Because of this, a doclet developed for Java 5 won't work under Java 1.4 (otherwise is possible, of course). However, as we found (after the preliminary v1.5 beta release), Java 1.4 appears to be still well in use. So, we have finally decided in DocFlex/Javadoc v1.5.x to support both Java versions (i.e. the new Doclet API 1.5 and the old Doclet API 1.4). Since the binaries compiled for Java 5 are not compatible with Java 1.4, now, DocFlex/Javadoc v1.5.x (both editions) includes two Java libraries: the one compiled for Java 5+ and another one compiled for Java 1.4. The Doclet DSM, on which any DocFlex/Javadoc templates are based, is always the same. That is, the Java 5 functionality (i.e. the mapping of entire Doclet API 1.5 on a virtual XML document model) is present in both libraries. However, in the version compiled for Java 1.4, everything concerned Java 5 is emulated by the Doclet DSM Driver itself. It happened to be very simple to implement. So, we've done this! As a result, any templates designed for either Java version will work fine under both Java 5+ and Java 1.4 as well. The templates simply won't "notice" the difference! |
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. |
A JavaDoc generator implemented as {DocFlex Doclet + template set} is controlled by lots of settings, which include:
So, besides command line options, DocFlex Doclet provides a more user-friendly way to control the template-based doclets interactively -- the Doclet GUI.
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):
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):
![]() |
|
![]() |
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!
This is an early version of the standard template set. It allows you to generate:
For more details about the basic template set, please see: DocFlex/Javadoc | Basic Templates
“JavadocPro” is a new template set available since the version 1.6.0. Using it you will be able to generate:
Here is a demo of framed HTML JavaDoc generated with JavadocPro Template Set (click on a screenshot to view the real HTML):
![]() |
![]() |
Further details about “JavadocPro” are available on the page: DocFlex/Javadoc | JavadocPro
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 was successfully working under 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.
Feature / Functionality | Limited Mode | Full Mode | Trial Mode |
---|---|---|---|
License type(s) | |||
Template Designer | ![]() |
![]() |
|
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).
|
![]() |
||
Execution of Basic Template Set
|
![]() |
![]() |
|
Execution of JavadocPro Template Set
See also:
DocFlex/Javadoc | JavadocPro | Licensing
|
![]() |
||
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
|
Feature / Functionality | Availability |
---|---|
License type | |
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).
|
|
Execution of Basic Template Set
|
![]() |
Execution of JavadocPro Template Set
See also:
DocFlex/Javadoc | JavadocPro | Licensing
|
|
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
|
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
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:
For example, class
com.sun.javadoc.ClassDoc
has a method methods()
, which returns an array of
com.sun.javadoc.FieldDoc
objects representing all fields of a Java class being documented. Those two classes and method
are mapped as the following:
com.sun.javadoc.ClassDoc
is mapped to DSM element ClassDoc
com.sun.javadoc.FieldDoc
is mapped to DSM element FieldDoc
ClassDoc.fields()
is mapped into parent/child relationship between ClassDoc
and FieldDoc
elements according to the following XML
DTD declaration:
<!ELEMENT ClassDoc (FieldDoc*)>
IDREF
type
(single- or multi-valued depending on the cardinality of the returned objects).
For example, method com.sun.javadoc.ClassDoc.interfaces()
returns ClassDoc
objects, which represent all interfaces implemented by a documented Java class. Those interfaces are not
part of this class. They exist independently. So, the relationship between the interfaces and the class
implementing them should be interpreted as association. Therefore, the method
ClassDoc.interfaces()
is mapped as an attribute interfaces
of the
ClassDoc
DSM element.
Here is how this might look in the form of an XML DTD declaration:
<!ATTRLIST ClassDoc interfaces IDREFS>
For example, method com.sun.javadoc.ClassDoc.isAbstract()
, which returns a boolean value,
is mapped to a isAbstact
attribute of the ClassDoc
DSM element.
Here is how this would looks in the form of a XML DTD declaration
(if BOOLEAN
data type was allowed in DTD):
<!ATTRLIST ClassDoc isAbstract BOOLEAN>
In effect, the tree visible on this picture represents all the Doclet API in a very simple but equally powerful form.![]()
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.
java.*
javax.*
org.*
|
javax.swing
package and subpackages:
|