DocFlex/Javadoc - “JavadocPro” Template Set
- What is JavadocPro?
- Key Features (What you can generate with it)
- Template Set Overview
- Advantages of JavadocPro
1. What is JavadocPro?
“JavadocPro” is a new template set
that implements a powerful Java API documentation generator in several output formats
with the support of filtering of classes and members by tags/annotations.
It employes almost all recent advances in DocFlex Technology!
2. Key Features (What you can generate with it)
Framed HTML Documentation
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
- Cross-Reference Pages
- Support Files
Standard Javadoc navigation bar
Switching between FRAMES / NO FRAMES views
Single File HTML Documentation
The same entire documentation can be equally generated as a single HTML file using
main template, it is possible not only to generate a single file HTML.
Simply, by switch the generator
to “RTF”, the same template will produce a highest quality RTF file!
These screenshots show pages of an RTF documentation generated by several JDK Source classes (click to see in full size):
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).
Table Of Contents.
See also DocFlex/Javadoc | Examples | RTF Demo
for more details about that demo RTF and other screenshots.
Using some of the available RTF
-> PDF converters,
you can also produce a top quality PDF documentation.
Here is a PDF JavaDoc generated in that way
(click on the screenshot to see/download the PDF file, 570 KB):
Such documentation can be used both for printing and publishing on the web.
Filtering of classes and members by tags and annotations
You can both:
This will equally work for all types of generated documentation.
- Exclude classes/members by tags/annotation
- Include classes/members by tags/annotation (opposite to exclusion)
More than 70 parameters to customize your JavaDoc
The parameters work similar to options provided by the Standard Doclet.
You can both edit them in a tree-like form using a graphic GUI
and specify directly on the command line (and even via some of the old
For further details about template parameters, please see:
3. Template Set Overview
The entire “JavadocPro” template set currently consists of 28 templates,
For detailed information about each template, please see:
DocFlex/Javadoc | JavadocPro | Templates
Main templates are those that can be specified for interpretation directly either with
on the Javadoc command line or in the Doclet GUI.
In effect, each main template is a driver for a particular kind of documentation generator.
Besides the main templates, there are many other templates
(called subtemplates) that are used internally.
Those templates work as procedures invoked from the main templates as well as from each other.
This template produces no output. Instead, it is called only once from either
PlainDoc.tpl or FramedDoc.tpl main templates
before any other processing starts. The template's job is to create element maps that are critical
for the working of other templates.
Basic Content Subtemplates
Generate pages (or sections) that provide primary information about the Java project
Generates the documentation Overview page/section (an equivalent of the
file generated by the
Generates a Package Overview page/section for every Java package being documented
(an equivalent of the
file generated by the
which includes package description, tags and summary tables of contained classes.
Generates a Class Details page/section for a class/interface/enum or an annotation type.
The class details may include the class description, various reference lists about it,
as well as the details of all documented members of that class (except nested classes).
This provides the bulk of the whole Java API documentation.
Cross-Reference Page Subtemplates
Generate pages of framed HTML documentation
that help to quickly find the necessary information
Generates the All Classes Summary page, which is loaded when clicking on
“All Classes” item in the
in framed HTML documentation.
for each documented package. The page describes which packages and classes use any API of the given package.
for each documented class. The page describes which packages, classes, methods, constructors and fields use
any API of the given class.
class/interface hierarchy pages.
These are the pages you reach using the “Tree” button in the
deprecated API page
'deprecated-list.html' file), which contains the list of deprecated APIs,
and the “Deprecated” link in the
to that page.
Generates a single
It is used when no splitting
of the index into multiple files has been specified.
Generates for a particular letter either a section of the whole
'index-all.html' generated by
or a corresponding separate index page (
This template generates the
serialized form page,
which provides information about serializable and externalizable classes.
This template generates the
constant field values page
'constant-values.html' file), which lists the static final fields and their values.
Support File Subtemplates
Generate files that help navigation of framed HTML documentation and connecting to it
This is the page you reach using the “Help” button in the
Generates the primary navigation page, which includes the lists all packages and other primary links.
It is used in the upper-left "overview"
Generates a navigation page with the list of all documented classes.
It is loaded in the lower-left "summary"
Generates a separate navigation page for each documented package,
which is loaded into the lower-left "summary"
on clicking on the corresponding package in the "overview"
file, which is a plain-text file that lists the names of all documented packages
(or those containing the documented classes).
Generate separate (relatively large) sections of the documentation (however, never separate files)
Generate a package summary table included in the general Overview (produced
Generates the Title Page (which will be the front page of the RTF documentation).
Generates the Table Of Contents of the documentation.
Called from other templates to generate small (but frequent) fragments of the documentation
Generates all navigation bars found the framed HTML documentation.
Generates the list of annotations (along with all related hyperlinks) of a package,
class, member or constructor/method parameter.
Processes a user-defined cross-reference to related documentation.
Processes most of the inline tags.
Adds the About section at the bottom of each separate output document.
It displays the information about DocFlex/Javadoc
product along with the hyperlinks to this website.
Since all the content and formatting of the generated JavaDoc is programmed entirely in the template set
(which, in effect, becomes the actual doclet), what previously were command-line options provided by the
now simply become template parameters.
But introducing and checking parameters in templates is much easier
than implementing some command-line options controlling a Java code.
(In fact, it is writing a parameter description what takes the most time in many cases!)
So, there can be a lot more template parameters than in the case of in traditional
“command-line options” approach.
“JavadocPro” currently provides
more than 70 parameters.
Parameter Inspector GUI
To control so many parameters,
DocFlex Doclet provides
a GUI that includes
the Parameter Inspector dialog
(which is invoked from the main dialog on clicking “Params” button for the specified template).
On the following screenshot you can see the Parameter Inspector loaded with the parameters of
(click to view an expanded form):
The inspector content is constructed dynamically from the
found in the given template.
Using Parameter Inspector, you can:
For further details, please see:
Documentation | DocFlex Doclet | Handling Template Parameters | Using Parameter Insector GUI
Edit each parameter according to its type.
View the parameter HTML description (it is also obtained from the template) as well as
the parameter internal name (the first line) and possible values, which must be specified in
when you set that parameter on the command line (see below).
Setting parameters from command line
Besides the Parameter Inspector dialog,
you can always set any template parameters directly on the
command line using
Documentation | DocFlex Doclet | Handling Template Parameters | Setting parameters from command line
Specifying parameters via Standard Doclet options
“JavadocPro” maps some of the
Standard Doclet options
to the default values of appropriate template parameters. This lets you using those options
instead of specifying the corresponding parameters.
For more information about this capability and its implementation, see also:
Below is the list of all supported Standard Doclet options along with the template parameters, to which they are mapped:
5. Advantages of JavadocPro
We suggest the following advantages of using
DocFlex/Javadoc + JavadocPro Template Set:
Generation of classic JavaDoc with a possibility
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:
Of course, the real life not always follows some canonical schemes!
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.
See more discussion about this problem here:
DocFlex/Javadoc | JavadocPro | Parameters | Filter Classes & Members
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
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:
Ultimately, you can program a completely different JavaDoc generator,
and even in a different format (particularly XML-based, e.g. DITA)!
Translate all JavaDoc text labels into any other language.
The primary way to do it is by modifying the templates in the Template Designer.
However, you can also edit templates directly as plain text (e.g. using Windows Notepad).
Templates files are plain text files in UTF-8 encoding.
You can change any text labels there and write any symbols (even hieroglyphs).
For that matter, see also:
Licensing of Templates | Custom Templates | Changing Templates Manually.
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).
What is needed for all this?
A license covering the Template Designer,
that is the full license for “DocFlex/Javadoc”
(see also Full Edition).
The “JavadocPro” template set is included in both
editions of DocFlex/Javadoc.
However, it will work differently depending on your license for
There are two modes:
limited and full.
Limited mode - Use it for free!
This mode is activated by default without any special license.
What you can:
What you cannot:
Full functionality - Get a DocFlex/Javadoc license and use everything!
JavadocPro will be fully unlocked
under the same “DocFlex/Javadoc” license that covers the
It will also allow you to customize all the templates as much as you need.