On this page, we shall overview the standard set of templates (provided within both DocFlex/Javadoc and DocFlex/Doclet downloads) and show examples of the output they produce.

The standard templates are subdivided into two categories:

The main templates, which are designed to produce a finished documentation and should be specified on the Javadoc command line or in the generator dialog. The main templates are located in the 'templates' directory of the DocFlex/Javadoc installation.
The subsidiary templates or subtemplates, which constitute a sort of library and are called from the main templates (as well as from each other) to generate fragments or separate files of the whole documentation. All subtemplates are contained in the 'templates/lib' directory of the DocFlex/Javadoc installation.

Template Description Called From

PlainDoc.tpl generates single-file documentation in any of the supported formats (HTML, RTF and TXT) generator (doclet)

FramedDoc.tpl generates framed hypertext documentation (HTML only) generator (doclet)

Subtemplates

init.tpl creates element maps PlainDoc.tpl, FramedDoc.tpl

Subtemplates called to generate either big sections of single-file documentation or separate documents for the “detail” frame of framed HTML documentation

overview-summary.tpl generates the overview for the whole documentation PlainDoc.tpl, FramedDoc.tpl

package-summary.tpl generates a package overview (i.e. description, tags and summary tables of contained classes) PlainDoc.tpl, FramedDoc.tpl

class.tpl generates the detailed documentation for a class (i.e. class, interface, enum or annotation type) PlainDoc.tpl, FramedDoc.tpl

Subtemplates called to generate small fragments of the detailed documentation

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

tags.tpl documents all general tags of a Doc item class.tpl, overview-summary.tpl, package-summary.tpl

inline-tag.tpl processes most of the inline tags class.tpl, tags.tpl, overview-summary.tpl, package-summary.tpl

see-link.tpl processes a user-defined cross-reference to related documentation class.tpl, tags.tpl, inline-tag.tpl

about.tpl prints the “about” information at the bottom of most of documents PlainDoc.tpl, class.tpl, overview-summary.tpl, package-summary.tpl

Subtemplates that generate separate reference files used only in framed HTML documentation

overview-frame.tpl generates the reference document for the whole documentation FramedDoc.tpl

all-classes-frame.tpl generates the reference document for all classes FramedDoc.tpl

package-frame.tpl generates the reference document for a package FramedDoc.tpl

package-list.tpl generates the package-list text file FramedDoc.tpl

2. Main Templates

These are the templates to be specified on the Javadoc command line or in the generator dialog to produce a finished Java API documentation.

PlainDoc.tpl

This main template is designed to generated a single-file documentation in any of the supported output formats (HTML, RTF and TXT), which may be particularly useful for printing.

The following screenshots show pages of an RTF demo documentation generated with PlainDoc.tpl (click to see in full size):

Here is how the template looks when loaded in the Template Designer:

Parameters

The template parameters are defined in the Template Properties dialog:

The parameters can be accessed within the FlexQuery-expressions which can control the behavior and output of some of the template components.

When generating documentation, the parameter values can be specified interactively in the Template Parameter Inspector invoked from the Generator Dialog (the inspector contents is constructed dynamically from the parameter definitions specified in the template):

Also, the template parameters can be passed via -P option on the Javadoc command line.

Here are the detailed descriptions of all parameters of PlainDoc.tpl template (that you can see in the inspector screenshot above). Those descriptions are also available within the Parameter Inspector dialog directly.

Parameter/Grouping

Description

Window Title Parameter name: windowTitle
Specifies the browser window title for the documentation. This is similar to -windowtitle option provided by Javadoc Standard doclet. In addition, if the selected output format supports pagination (RTF), the same text will appear on the page footers.

Documentation Title Parameter name: docTitle
Specifies the title to be placed at the the top of the documentation overview.

Include

deprecated API
Parameter name: include.deprecated
Controls whether to generate documentation for any deprecated API.

Details Of
This group of parameters controls how much details are included in the generated documentation. This may be important for printing, since the documentation with all details may occur too big to be printable.

overview
Parameter name: include.details.overview
Specifies whether to include the overview summary for the whole documentation.

packages
Parameter name: include.details.packages
Specifies whether to include the details of packages. If false (unchecked), only classes separately specified on the Javadoc command line will be documented.

classes
Parameter name: include.details.classes
Specifies whether to include details of classes. If false (unchecked), only overview for each package will be generated without the detailed documentation for the contained classes.

inner classes
Parameter name: include.details.innerClasses
Specifies whether inner classes should be included into the generation scope. If true (checked), the inner classes contained within those already being documented will also be fully documented. If false, only summaries of the inner classes will be generated.

members
Parameter name: include.details.members
Specifies whether to include details of class members (i.e. methods and fields). If false (unchecked), only overview for each class will be generated without the details for the class' members.

initial values
Parameter name: include.details.initialValues
Specify whether the initial values of fields should be shown in the documentation.

Tags
This group of parameters controls whether to include in the generated docs the sections associated with some tags.

@version
Parameter name: include.tag.version
Include the @version text in the generated docs.

@author
Parameter name: include.tag.author
Include the @author text in the generated docs.

@since
Parameter name: include.tag.since
Include the @since text in the generated docs.

Custom tags
Parameter name: include.tag.custom
Include the text of any user-defined (non Javadoc) tags in the generated docs.

Exclude Specify what should be entirely excluded from the generation scope.

By Tags
This group of parameters allows you to exclude from the generated documentation classes, fields and methods with specified tags (custom or not).

classes & members
Parameter name: exclude.byTags.all
Specify tags by which both classes and class members (i.e. fields, constructors and methods) are completely excluded from the generated documentation.
A class is excluded when at least one of the conditions is met:

The class has one of the specified tags.

This is an inner class and one of its enclosing classes has one of the specified tags.

A class member is excluded according to one of the conditions:

The member has one of the specified tags.

The member's class has one of the specified tags.

The member's class is an inner class and one of its enclosing classes has one of the specified tags.

Therefore, when a class has one of the tags specified in this parameter, neither that class nor anything defined in it (i.e. members and inner classes) will ever appear in the documentation.
The multiple exclude-tag names must be separated with new lines ('\n'), semicolons (';') or colons (':'). For example:
@exclude @omit

classes
Parameter name: exclude.byTags.classes
This parameter allows you to hide completely from the generated documentation some intermediate classes of your internal implementation (that for some reasons need to be public), however, preserve documenting of some fields and methods (defined within those classes) which are supposed to be part of an open API.
This may be particularly helpful when you will need next time to change your implementation while keeping intact what you have declared in your open API.
The tags specified in this parameter are treated as the following.
A class will be never mentioned in the documentation when at least one of the conditions is met:

The class has one of the specified tags.

This is an inner class and one of its enclosing classes has one of the specified tags.

Each inheritable member of the excluded class that otherwise (without that parameter) would be documented will appear in every direct descendant of that class being documented as if that member has been defined directly there.
Overall effect should be that the generated documentation will look as if the excluded classes themselves did never exist at all, however, everything else is in place and correct.
The multiple exclude-tag names must be separated with new lines ('\n'), semicolons (';') or colons (':'). For example:
@exclude @omit

members
Parameter name: exclude.byTags.members
Specify tags by which only class members (i.e. fields, constructors and methods) are selectively excluded from the generated documentation.
A class member, which otherwise (without this parameter) would be documented, is excluded when it has at least one of the specified tags.
The multiple exclude-tag names must be separated with new lines ('\n'), semicolons (';') or colons (':'). For example:
@exclude @omit

By Annotations
This group of parameters provides an alternative way of excluding classes and class members from the generated documentation.

As you know, one of the new language features introduced in Java 5 is “annotations”. Annotations are essentially similar to tags. However, unlike tags, they are specified not within Java comments, but directly in Java code. That is, annotations are processed by the Java compiler itself and can be retained in the compiled binary classes (which is impossible with tags).
So, similar to tags you can mark some of the classes and members with annotations and, then, filter them out by those annotations from the generated documentation.
But, why would you need to use annotations? Why are tags not enough?
Let's suppose, you have a library of some core Java classes for internal use. That library is quite a separate thing. So, you may use it in different projects (or different people are using it). Therefore, you maintain that library in a precompiled binary form as a jar-file.
Now, you are developing a project, in which you use that internal library. You want to publish certain classes of that project as an open API to your system. But some of those classes you want to publish are inherited from the classes of your internal library (or implement interfaces from it). The Java API documentation generated by Javadoc would mention those internal classes as superclasses (implemented interfaces) of your API. But you do not want them to be visible in the published documentation (they are internal after all)! How can you do that?
Marking your internal classes with tags to be excluded by them will not work, because your tags will not get into the compiled jar-file.
Here is where annotations can help! Let's see how you can do it.
First, you need to define your annotation type like the following (all names are for example):

package myprojects.core.util; public @interface Internal { }

These lines should be saved as 'Internal.java' file located in 'myprojects/core/util' package.
Note, as with any Java class, the defined annotation type has a fully qualified name, which will be the string: 'myprojects.core.util.Internal'. Only the fully qualified name can be used to find annotations of a given type.
Now, you can use this annotation type to mark your internal classes. Here is how:

package myprojects.core.classes; ... import myprojects.core.util.Internal; @Internal public class MyIterator { ... }

After that, you can exclude all classes marked with that annotation from the generated documentation by specifying the annotation type qualified name 'myprojects.core.util.Internal' in the exclude.byAnns.classes parameter.
This will equally work both with the classes defined in the Java sources and the binary classes found on the Javadoc classpath!

classes & members
Parameter name: exclude.byAnns.all
Specify annotation types by which both classes and class members (i.e. fields, constructors and methods) are completely excluded from the generated documentation.
A class is excluded when at least one of the conditions is met:

The class has an annotation of one of the specified types.

This is an inner class and one of its enclosing classes has an annotation of one of the specified types.

A class member is excluded according to one of the conditions:

The member has an annotation of one of the specified types.

The member's class has an annotation of one of the specified types.

The member's class is an inner class and one of its enclosing classes has an annotation of one of the specified types.

Therefore, when a class has one of the annotations specified in this parameter, neither that class nor anything defined in it (i.e. members and inner classes) will ever appear in the documentation.
Each annotation type must be specified with its fully qualified name (e.g. java.lang.Deprecated). Multiple annotation type names must be separated with new lines ('\n'), semicolons (';') or colons (':'). For example:
my.core.util.Internal my.project.api.Exclude

For more details about using annotations, see description of the Exclude | By Annotations parameter group.

classes
Parameter name: exclude.byAnns.classes
This parameter allows you to hide completely from the generated documentation some intermediate classes of your internal implementation (that for some reasons need to be public), however, to preserve documenting of some fields and methods (defined within those classes) which are supposed to be part of an open API.
This may be particularly helpful when you will need next time to change your implementation while keeping intact what you have declared in your open API.
The annotation types specified in this parameter are treated as the following.
A class will be never mentioned in the documentation when at least one of the conditions is met:

The class has an annotation of one of the specified types.

This is an inner class and one of its enclosing classes has an annotation of one of the specified types.

Each inheritable member of the excluded class that otherwise (without that parameter) would be documented will appear in every direct descendant of that class being documented as if that member has been defined directly there.
Overall effect should be that the generated documentation will look as if the excluded classes themselves did never exist at all, however, everything else is in place and correct.
Each annotation type must be specified with its fully qualified name (e.g. java.lang.Deprecated). Multiple annotation type names must be separated with new lines ('\n'), semicolons (';') or colons (':'). For example:
my.core.util.Internal my.project.api.Exclude

For more details about using annotations, see description of the Exclude | By Annotations parameter group.

members
Parameter name: exclude.byAnns.members
Specify annotation types by which only class members (i.e. fields, constructors and methods) are selectively excluded from the generated documentation.
A class member, which otherwise (without this parameter) would be documented, is excluded when it has an annotation of one of the specified types.
Each annotation type must be specified with its fully qualified name (e.g. java.lang.Deprecated). Multiple annotation type names must be separated with new lines ('\n'), semicolons (';') or colons (':'). For example:
my.core.util.Internal my.project.api.Exclude

For more details about using annotations, see description of the Exclude | By Annotations parameter group.

Omit This group of parameters controls which information should not appear in the generated documentation.

Package qualifiers started with
Parameter name: omit.packageQualifiers.for
Specify the packages whose qualifying names should be omitted from ahead of class names in parameters, types, referenced classes (like exception lists, implemented interfaces, etc.), @see tags and {@link} tags in comments.
The packages to omit are specified as the list of package name prefixes delimited with new lines ('\n'), semicolons (';') or colons (':'). For example:
java.lang. javax.swing.

When a particular fully-qualified name is decided whether to be shortened, the answer will be yes when the full name starts with one of the specified prefixes.

All package qualifiers
Parameter name: omit.packageQualifiers.all
If selected, all qualifying package names will be omitted from ahead of class names in parameters, types, referenced classes (like exception lists, implemented interfaces, etc.), @see tags and {@link} tags in comments.

Inherited member lists for packages
Parameter name: omit.inheritedMemberLists.for
Suppress generation of lists of the inner classes, fields or methods inherited from those classes/interfaces, which belong to the packages specified with this parameter.
This parameter may be especially useful to suppress long lists of the class members inherited from the standard Java API classes and, in such a way, to considerably reduce the output documentation.
The packages, whose classes/inerfaces should not appear in the "inherited from ..." lists, are specified as the list of the package name prefixes delimited with new lines ('\n'), semicolons (';') or colons (':').
For example, the following will exclude lists of the members inherited from most of the standard Java API classes:
java.lang. javax.swing.

All inherited member lists
Parameter name: omit.inheritedMemberLists.all
If selected, no lists of inherited inner classes, fields or methods will be generated at all.

Formatting This group of parameters controls some formatting features of the output documentation specifically generated by this template.

Start package from new page
Parameter name: fmt.page.breakBefore.package
If true (checked), each package documentation will be started from a new page.

Start class from new page
Parameter name: fmt.page.breakBefore.class
If true (checked), each class documentation will be started from a new page.

FramedDoc.tpl

This is the second main template provided in downloads. It is designed to generated a framed documentation similar to that produced by the Standard Javadoc Doclet.

As for now, such templates are supported only by HTML output format. However, once implementations of new format arrive in the next DocFlex versions, it's quite imaginable that a concept of interactive frames would also be possible in some of them (PDF, for instance).

The following is a framed HTML demo documentation generated with FramedDoc.tpl (click on the picture to see the live HTML):

Here is how the template looks when loaded in the Template Designer:

As you can see, this template consists mainly of calls of subtemplates, which generate the documents displayed in the frame windows. Besides this, the next important thing contained in the template is the frameset structure that is specified in the template properties:

The frameset structure is defined in the form of a tree. The condition icon appears near the node that can be enabled/disabled dynamically according to the Enabling Condition specified on the right panel. This allows customization of the frameset structure dynamically and excluding those frames that are not needed for a particular documentation.

3. Initialization Subtemplate

init.tpl

This template does not produce any 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.

Element maps are essentially hash-maps. They map keys to sets of Doclet DSM's elements (which, as you know, are the representations of the objects operated by Doclet API). Most commonly, as the keys are used the element unique identifiers (see GOMElement.id), which means that some sets of elements are mapped to other sets of elements. This can be used to quickly find by certain elements some other elements according to specific functional relations. That makes possible resolving very complicated queries and provides capabilities for sophisticated data mining.

Here's an example. From the Java source code (via the Doclet API), we can easily obtain the following things:

The list of all classes in the project
For a given class -- the list of all interfaces it directly implements
For a given class -- its superclass
For a given interface -- the list of all interfaces it directly extends

Now, for a given interface, we want to know: Which classes in the project do directly or indirectly implement it? Apparently, the answer is implicitly contained in all those items above. But how to find it?

Using an element map, it is possible. The element map is created as the following:

All classes in the project are iterated.
For each class (according to the items 2-4 in the list above), we find all interfaces that class directly or indirectly implements.
For each found interface and the class implementing it, we add a mapping so that the interface's element ID becomes a key and the element representing the class is put in the map by that key.

As a result, we have an element map that maps each interface to the list of all known classes implementing it. The following screenshots show the init.tpl template (click to enlarge) and how the creating of such an element map is programmed:

On the screenshot above, the function putElementsByKeys() puts in the element map named "All Known Implementing Classes" a single element representing a class, however, by a number of keys at once. Those keys are the unique identifiers of all interfaces that class directly/indirectly implements. The list of interfaces is obtained using Location Rules. The function getElementIds() converts the enumeration of elements (representing the found interfaces) into the array of their unique IDs.

The "All Known Implementing Classes" element map is further used within the class.tpl template to generate that very list for a particular interface.

4. Detail Subtemplates

The subtemplates from this group are called directly from both of the main templates. Each subtemplate, depending on where it is called from, plays two different roles:

when called from PlainDoc.tpl, it generates a big sections of the single-file documentation;
when called from FramedDoc.tpl, it produces a separate document for the “detail” frame of framed HTML documentation.

overview-summary.tpl

This template generates the overview for the whole documentation.

The next screenshot shows an HTML file produced by this template:

package-summary.tpl

This template generates a package overview (i.e. description, tags and summary tables of contained classes):

The next screenshot shows an HTML document produced by this template:

class.tpl

This template generates the full documentation for a class/interface/enum or an annotation type. It is the most complex template, whose only little part is visible on this screenshot:

The following screenshots show the HTML documents generated by class.tpl for a class, interface, enum and annotation type respectively (click on the screenshots to see HTML):

5. Fragment Subtemplates

The subtemplates from this group are used to generate small fragments of the detailed documentation. They are called from many different locations (including from each other).

annotations.tpl

This template generates the list of annotations (along with all related hyperlinks) of a package, class, member or constructor/method parameter. On the following demo screenshots, you can see how such annotations look in a generated documentation:

Here is the annotations.tpl template itself when loaded in the Template Designer (click to see a large screenshot):

The following are the screenshots of two main stock-section of this template. Stock-sections are the template parts which behave similar to procedures in ordinary programming languages. Each stock-section can be called from different locations of the template (including from within the stock-section itself).

This particular stock-section reproduces a single annotation (as it would be specified in the Java code):

This one reproduces an annotation's element value:

tags.tpl

This template documents all general tags (like “Author”, “See Also” and so on) of a Doc item:

It is called from

overview-summary.tpl (that generates the whole documentation overview);
overview-summary.tpl (that generates the overview of a package);
class.tpl (in several locations, which generate the detailed documentation of program elements).

If you need to add documenting of your own specific tags, you may program this exactly by modifying the tags.tpl template.

Note: Some program elements (e.g. fields) may have additional tags that are documented locally, not by this template.

inline-tag.tpl

This template processes most of the inline tags. The inline tags are those looking like:

{@tag ...}

They can be placed directly within Java comments to be replaced automatically by Javadoc with certain values (see JAVADOC TAGS for details).

In fact, Javadoc does not fully process the inline tags by itself. Rather, it only parses them and provides for further processing to a doclet via Doclet API. It is the doclet, who has to replace the inline tags with the useful values according to their meanings.

That is exactly what this template does (as part of the doclet). Here is how it looks when open in the Template Designer (click to enlarge):

Each section catches and processes a specific inline tag. On the following screenshot, those sections are shown when expanded:

If you need to program processing of your own inline tags, the inline-tag.tpl template is where you can do this.

Note: The {@inheritDoc} tag that can be used in a method comments needs a very special processing, which is programmed locally in class.tpl template, where a method's documentation is also generated.

see-link.tpl

This template processes a user-defined cross-reference to related documentation.

When Javadoc parses Java comments, it creates by each @see or {@link} tag a com.sun.javadoc.SeeTag object. Those objects should be processed by a doclet into cross-reference hyperlinks (to the location both within the generated documentation and external ones).

The see-link.tpl template does just this. The following screenshots show its root section block both in collapsed and expanded form:

about.tpl

This template just adds the “about” section at the bottom of each separate output document. That section displays the information about DocFlex/Javadoc product along with the hyperlinks to this website.

You can easily suppress it by disabling the Area Section, as shown on the screenshot:

(Or replace it with something of your own.)

6. Reference List Subtemplates

These subtemplates are called only directly from FramedDoc.tpl to generate separate reference files used only in framed HTML documentation.

overview-frame.tpl

This template generates the reference document for the whole documentation (placed in the top-left “overview” frame).

all-classes-frame.tpl

This template generates the reference document for all classes (placed in the the bottom-left “summary” frame).

package-frame.tpl

This template generates the reference document for a package (placed in the the bottom-left “summary” frame).

package-list.tpl

This template generates the package-list file, which is a plain-text file that lists the names of all documented packages (or those containing the documented classes).

This file is used by Javadoc to generate hyperlinks to an external Java API documentation, whose location is specified with -link or -linkoffline options on the Javadoc command line.

The package-list file generated by this template allows linking any other Java API documentation (including one generated by the Standard Doclet) to the framed HTML documentation produced with FramedDoc.tpl template.

(Note: The opposite is possible as well, as DocFlex Doclet also supports -link and -linkoffline options.)

The following is the screenshot of package-list.tpl template:

This is the simplest template from the whole set. It consists of the only Element Iterator section that produces the package list. Here is how the iteration scope is specified:

The first Location Rule collects all packages directly specified on the Javadoc command line. The second Location Rule collects the packages of all classes directly specified on the Javadoc command line. Both Location Rules are interpreted against the template's root element, which is associated with the com.sun.javadoc.RootDoc instance received by the doclet. (The repeating packages are eliminated from the result collection.)

The package-list.tpl template is called from the FramedDoc.tpl main template (where the corresponding Call Template section it is specified to produce a plain-text file -- not an HTML file as all other subtemplates).

An example of a package-list file produced by this template can be found at: http://www.filigris.com/products/docflex_javadoc/examples/html/package-list
(which is a part of a demo framed HTML documentation).