“JavadocPro” is a new template set for DocFlex/Javadoc 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

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

See also DocFlex/Javadoc | Examples | RTF Demo for more details about that demo RTF and other screenshots.

PDF Documentation

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:

Exclude classes/members by tags/annotation
Include classes/members by tags/annotation (opposite to exclusion)

This will equally work for all types of generated documentation.

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

For further details about template parameters, please see:

Template Set Overview | Template Parameters
DocFlex/Javadoc | JavadocPro | Parameter Tree (descriptions of all JavadocPro parameters)
DocFlex/Javadoc | JavadocPro | Templates | Parameters (describes how parameters are defined and used)

3. Template Set Overview

The entire “JavadocPro” template set currently consists of 28 templates, which include:

2 main templates
26 subtemplates

For detailed information about each template, please see: DocFlex/Javadoc | JavadocPro | Templates

Main Templates

Main templates are those that can be specified for interpretation directly either with -template option 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.

Main Template Summary

FramedDoc.tpl Generates framed HTML Java API documentation identical to the classic JavaDoc.

PlainDoc.tpl Generates single-file JavaDoc (both RTF and HTML).

Subtemplates

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.

Subtemplate Summary

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

overview.tpl Generates the documentation Overview page/section (an equivalent of the overview-summary.html file generated by the Standard Doclet).

package.tpl Generates a Package Overview page/section for every Java package being documented (an equivalent of the package-summary.html file generated by the Standard Doclet), which includes package description, tags and summary tables of contained classes.

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

class-summary.tpl Generates the All Classes Summary page, which is loaded when clicking on “All Classes” item in the navigation bar in framed HTML documentation.

package-use.tpl Generates a “use” page for each documented package. The page describes which packages and classes use any API of the given package.

class-use.tpl Generates a “use” page for each documented class. The page describes which packages, classes, methods, constructors and fields use any API of the given class.

class-tree.tpl Generates class/interface hierarchy pages. These are the pages you reach using the “Tree” button in the navigation bar.

deprecated-list.tpl Generates the deprecated API page ('deprecated-list.html' file), which contains the list of deprecated APIs, and the “Deprecated” link in the navigation bar to that page.

index-all.tpl Generates a single index page ('index-all.html' file). It is used when no splitting of the index into multiple files has been specified.

index-letter.tpl Generates for a particular letter either a section of the whole index file (i.e. 'index-all.html' generated by index-all.tpl) or a corresponding separate index page ('index-*.html').

serialized-form.tpl This template generates the serialized form page, which provides information about serializable and externalizable classes.

constant-values.tpl 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

help-doc.tpl Generates the help page. This is the page you reach using the “Help” button in the navigation bar.

overview-frame.tpl Generates the primary navigation page, which includes the lists all packages and other primary links. It is used in the upper-left "overview" frame.

all-classes-frame.tpl Generates a navigation page with the list of all documented classes. It is loaded in the lower-left "summary" frame.

package-frame.tpl Generates a separate navigation page for each documented package, which is loaded into the lower-left "summary" frame on clicking on the corresponding package in the "overview" frame.

package-list.tpl Generates a Package List file, which is a plain-text file that lists the names of all documented packages (or those containing the documented classes).

Section Subtemplates Generate separate (relatively large) sections of the documentation (however, never separate files)

package-summary.tpl Generate a package summary table included in the general Overview (produced overview.tpl template).

title-page.tpl Generates the Title Page (which will be the front page of the RTF documentation).

TOC.tpl Generates the Table Of Contents of the documentation.

Fragment Subtemplates Called from other templates to generate small (but frequent) fragments of the documentation

navbar.tpl Generates all navigation bars found the framed HTML documentation.

annotations.tpl Generates the list of annotations (along with all related hyperlinks) of a package, class, member or constructor/method parameter.

see-link.tpl Processes a user-defined cross-reference to related documentation.

inline-tag.tpl Processes most of the inline tags.

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

Template Parameters

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 Standard Doclet 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 FramedDoc.tpl (click to view an expanded form):

The inspector content is constructed dynamically from the parameter definitions found in the given template.

Using Parameter Inspector, you can:

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 -p option, when you set that parameter on the command line (see below).

For further details, please see: Documentation | DocFlex Doclet | Handling Template Parameters | Using Parameter Insector GUI

Setting parameters from command line

Besides the Parameter Inspector dialog, you can always set any template parameters directly on the command line using -p option.

Please see: 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 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:

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

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

Ultimately, you can program a completely different JavaDoc generator, and even in a different format (particularly XML-based, e.g. DITA)!

What is needed for all this? A license covering the Template Designer, that is the full license for “DocFlex/Javadoc” (see also Full Edition).

6. Licensing

The “JavadocPro” template set is included in both editions of DocFlex/Javadoc. However, it will work differently depending on your license for DocFlex/Javadoc software.

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:

Generate framed HTML JavaDoc with the same functionality as provided by the standard Javadoc.

If you are not particularly happy with the new JavaDoc design introduced in Java 7, you can use “JavadocPro” to generate the classic-looking JavaDoc under Java 7 too.

All template parameters equivalent to Standard Doclet options will be unlocked.
That's free!

What you cannot:

Filter classes and members by tags/annotations (the corresponding template parameters will be disabled).
Generate single-file HTML and RTF JavaDoc (the PlainDoc.tpl main template will be disabled).

Full functionality - Get a DocFlex/Javadoc license and use everything!

JavadocPro will be fully unlocked under the same “DocFlex/Javadoc” license that covers the Full Edition. It will also allow you to customize all the templates as much as you need.