FlexDoc/Javadoc - JavadocClassic - 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. Each main template effectively represents a separate documentation generator.

FramedDoc.tpl

This is a main template to generate framed HTML Java API documentation identical to the standard JavaDoc.

It works by calling all other templates that generate various documentation pages/files as well as it produces 'index.html' – the frameset file to display the documentation. See also: FramedDoc.tpl | Template Interpretation.

The following screenshot shows the template's root section block, where calling of all subtemplates happens (click to enlarge):

Here is a sample documentation generated with this template (click a screenshot to view the real HTML):

Template Location:

{flexdoc-javadoc}/templates/classic/FramedDoc.tpl

Controlled By Parameters:

See: FlexDoc/Javadoc | JavadocClassic | Parameters

Called From:

generator (doclet)

Calls:

init.tpl, overview.tpl, overview-frame.tpl, module.tpl, module-frame.tpl, package.tpl, package-frame.tpl, package-summary.tpl, package-use.tpl, class.tpl, class-summary.tpl, class-use.tpl, class-tree.tpl, allclasses-frame.tpl, index-all.tpl, index-letter.tpl, deprecated-list.tpl, constant-values.tpl, serialized-form.tpl, help-doc.tpl, element-list.tpl

Template Interpretation

The FramedDoc.tpl template is interpreted as follows:

First, the “Template Init Expression” specified in the template properties is processed:
That, in turn, invokes the execution of “Init” stock-section:

This stock-section generates no output. Rather, it calls from itself the init.tpl template to create element maps. Element maps are essentially hash-maps, which help to resolve very complicated queries. They are used in almost all other templates (including even init.tpl itself) and are critical for the working of the whole template set.
Further, the template's root section block is processed:

It does the following:
1. overview.tpl template is called to generate the Overview page for the whole documentation.
2. overview-frame.tpl template is called to generate the upper-left frame navigation page.
3. allclasses-frame.tpl template is called to generate a navigation page with the list of all documented classes.
4. All included modules are iterated. For each module:
  1. module.tpl template generates the Module Documentation page.
  2. module-frame.tpl template generates the module navigation page.
5. All included packages are iterated. For each package:
  1. package.tpl template generates the Package Documentation page.
  2. package-frame.tpl template generates the package navigation page.
  3. class-tree.tpl template generates the Class/Interface Hierarchy page for the package.
  4. class-use.tpl template generates the Package Usage page.
  5. All classes in the package that are to be documented are iterated. For each class:
    1. class.tpl template generates the Class Documentation page.
    2. class-use.tpl template generates the Class Usage page.
6. class-tree.tpl template is called to generate the Class/Interface Hierarchy page for all packages.
7. deprecated-list.tpl template generates the Deprecated API page.
8. constant-values.tpl template generates the Constant Field Values page.
9. serialized-form.tpl template generates the Serialized Form page.
10. class-summary.tpl template generates the All Classes index.
11. package-summary.tpl template generates the All Packages index.
12. The documentation Index is generated:
  1. First, a temporary “index” element map is created, which is essential for building of the index (see the “generate index” Folder Section | Properties | Processing | Init Expression tab)
  2. If index splitting was specified, all relevant index letters are iterated and the index-letter.tpl template is called for each to generate a separate file.
  3. Otherwise, the index-all.tpl template is called to generate the single index page.
13. help-doc.tpl template generates the documentation Help page.
14. element-list.tpl template generates the Package List file.

At this point, all document files have been already generated. What is left is a frameset file.

Doclet API Terminology

Selected

–

An element is considered to be selected, if the selection controls allow it to be documented. (Note that synthetic elements are never selected.)

Specified

–

The set of elements specified by the user are considered to be specified elements. Specified elements provide the starting points for determining the included elements to be documented.

Included

–

An element is considered to be included, if it is specified, if it contains a specified element, or it is enclosed in a specified element, and is selected. Included elements will be documented.

Generation of Frameset

The HTML frameset file (normally named 'index.html') starts the whole documentation to display particular HTML documents in three frame windows:

Frameset Diagram

The frameset file is generated according to the definition specified in the “Output File | Frameset Structure” tab of the FramedDoc.tpl properties dialog:

FramedDoc.tpl - Frameset Definition

The expression specified in the “Source Expression” field (on the right panel) should return the pathname (or URL) of a document to be initially loaded in the given frame.

However, the initial content of the detail frame may be overridden dynamically by the Javascript, which is inserted in index.html according the “HTML Head Expression”:

FramedDoc.tpl - HTML Head Expression

This particular Javascript obtains a URL parameter (specified after '?' in the initial URL) passed to index.html. If the parameter exists, the detail frame will be reloaded according to the new URL found in the parameter. That allows you to construct URLs like this one:

http://www.flexdoc.xyz/flexdoc-javadoc/classic/demo/html/FramedDoc/index.html?java.base/java/lang/StackOverflowError.html

which will open the frameset documentation directly on a specified page.

SingleDoc.tpl

This main template generates single-file JavaDoc (both RTF and HTML).

It works similar to FramedDoc.tpl, however, now all subtemplates called from it generate sections of the same single output file. Here are a few screenshots of such an output:

RTF JavaDoc:
Single-file HTML JavaDoc:

Template Location:

{flexdoc-javadoc}/templates/classic/SingleDoc.tpl

Controlled By Parameters:

See: FlexDoc/Javadoc | JavadocClassic | Parameters

Called From:

generator (doclet)

Calls:

init.tpl, title-page.tpl, TOC.tpl, overview.tpl, module.tpl, package.tpl, class.tpl, about.tpl demo-incomplete.tpl

Using styles to render CSS classes

As the HTML markup in Java doc-comments becomes more sophisticated, now the JDK API source code uses CSS classes to style various things. Among them, the following three kinds of tables:

CSS class	Description
borderless	No borders, vertical margins, styled caption. This style is provided for use with existing doc comments. In general, borderless tables should not be used for layout purposes.
plain	Plain borders around table and cells, vertical margins, styled caption. Best for small tables or for complex tables for tables with cells that span rows and columns, when the "striped" style does not work well.
striped	Borders around the table and vertical borders between cells, striped rows, vertical margins, styled caption. Best for tables that have a header row, and a body containing a series of simple rows.

For instance, a striped table rendered by HTML browsers as follows (click to view within the HTML documentation):

Since HTML tags and CSS rules cannot be interpreted directly in a non-HTML output (like RTF), to achieve a similar result in those formats, FlexDoc/Javadoc can render some HTML elements and CSS classes using template formatting styles.

SingleDoc.tpl main template includes the definitions of such rendering for all the three user table styles. Here is how it is done for striped tables:

An HTML Rendering Rule is defined to render <table> elements with 'striped' CSS class:
The formatting styles to render striped tables. The 2nd and 3rd screenshots is the style for striped rows.
Now, the same striped table can be rendered in RTF as well:

Template Parameters

This section explains what template parameters are for, how they are defined and used in templates. For the details about particular parameters provided by the JavadocClassic template set, please see: JavadocClassic | Parameters.

The parameters defined in main templates are used:

To control the execution of the entire template application
To pass certain data directly from the command line to be inserted in the generated output (e.g. “Window Title” parameter)

In that way, the template parameters work similar to options provided by the Standard Doclet.

Additionally, template parameters are extensively used internally, across the whole template set:

To pass data between templates (i.e. subtemplates)
As shortcuts to the values that are calculated only once per a template call and further frequently used both within that template and the subtemplates called from it (see also Default Value Expression and Auto-Passed properties).

How parameters are defined

To be accessed within a template, any template parameters must be defined in the “Parameters” tab of the template properties:

FramedDoc.tpl - definitions of template parameters

Definition of single parameter

A template parameter is defined with the series of properties:

definition of a single parameter

Here are the descriptions of most important template parameter properties:

Property	Description
Name	Specify the parameter internal name. This name uniquely identifies the parameter within the template. It is also used to automatically pass the parameter value to equally named parameters in called subtemplates (see Auto-Passed property). This very name must be specified with a -p option, when you want to pass the parameter value from the command line.
Title	Specify the parameter title, which it will appear in the Parameter Inspector. The title is in effect a very short description of the parameters.
Description	Specify the parameter full description that will be shown in the bottom panel of the Parameter Inspector when the parameter is selected. The description may include some HTML markup. It may also include `${include <url>}` macros, which are expanded dynamically with the content of the external files referenced from them. This makes possible to store the actual parameter descriptions (or parts of them) separately from the templates.
Enabling Condition	Specify a boolean FlexQuery that determines whether the parameter is enabled. When that query is specified it is calculated dynamically each time the template starts. When the query returns `false` the parameter becomes disabled. The disabling of the parameter indicates that according to all other settings this parameter is not expected to be actually used during the processing, that is its value is irrelevant. The disabled parameter won't accept any external value and, instead, is assigned only with its default value (see Default Value property). In the Parameter Inspector, the enabling condition is evaluates also each time any other parameters changed. The disabled parameters are shown with the disable color and cannot be edited.
Group	Specify whether the parameter is the head of a parameter group. The group constitutes a node of the parameter tree, in which the parameters are organized in the Parameter Inspector. The group may have additional properties, such as its own enabling condition, which may disable all the parameters within the group. A parameter marked as a group may still serve as the actual parameter (that is, to have its own value) or may be just the group heading (with the void value).
Type	Specify the data type of the parameter value.
List	Specify whether this is a multi-valued parameter. See Also: Documentation \| FlexDoc Doclet \| Handling Template Parameters \| Multi-valued (list) parameters
Default Value	Specify the default value of the parameter.
Expression	Specify the FlexQuery to calculate the default value of the parameter. When specified, the query provides the default value of the parameter. (It will override any default value specified statically in the Default Value property). The default value query is calculated dynamically (after the template processing has been started and the parameter default value is requested the first time). In the Parameter Inspector, the Default Value Expression is evaluated also each time when any other parameters changed, to refresh the value of the parameter when it is set as default. In JavadocClassic template set, it is supported the mapping of some Standard Doclet options to the default values of corresponding template parameters. This is implemented exactly here in the Default Value Expression property with the use of `hasOption()` and `getOption()` functions. See also: JavadocClassic \| Template Set Overview \| Template Parameters \| Specifying parameters via Standard Doclet options
Fixed	Indicates that the parameter value is fixed. A fixed parameter is assigned only with its default value specified in the template. However, unlike disabled parameters, it is expected to be used and won't be shown in the Parameter Inspector as disabled. This setting is needed because the same parameter (used across the template set) may be editable in one main template and fixed in other, because the only constant value makes sense for it. (For example, such is “Generate \| Overview” parameter.)
Auto-Passed	Indicates that by default the value of this parameter will be automatically passed (propagated) to all subtemplates called from the given one. (This will happen even when some of the intermediately called subtemplates do not define this parameter). This property is `true` by default. However, the auto-passing stops On a template, where this parameter is defined with auto-passed `false`. In a template call, where for this parameter, the passed value is specified explicitly. This parameter auto-passing is widely used in FlexDoc templates! For instance, many internal parameters are defined only to represent certain values calculated dynamically once per a template call. Further, such a parameter is automatically passed to other subtemplates, where the same value may be needed again. This allows avoiding the calculation of the same value many times, thereby improving the performance of the whole template application.
Hidden	Indicates that the parameter must be invisible in the Parameter Inspector. This is typically needed for internal parameters defined within main templates. (See the note to Auto-Passed property for why such parameters are needed.)

Parameter Inspector

By the parameter definitions specified in a main template the Parameter Inspector dialog is constructed. It is invoked from the Doclet GUI to allow specifying all the parameters interactively:

How parameters are used in templates

Template parameters are used in FlexQuery expressions specified in templates to control various properties of template components (such as enabling conditions and etc.)

The only way to access template parameters is using one of the Template Parameters functions. The getParam() function is main of them.

You can find all those functions (along with their descriptions) the Expression Assistant dialog invoked from the Template Designer | Help menu as well as from any of the FlexQuery Expression Editors (by clicking the "?" button).