FlexDoc/Javadoc - JavadocClassic - Templates

Description Subtemplates

Deal with all sorts of text descriptions that originate from doc-comments in the Java code and elsewhere, including any images provided through embedded HTML <img> tags.

text.tpl

This template generates all text descriptions found in the documentation, which originate from the doc-comments in the Java code.

This includes also any embedded images provided via HTML <img> tags.

Here is the template's root section block, which contains just a call of 'Output' stock-section that generates everything. Such a construct is needed because that stock-section recursively calls itself and therefore needs to have a name. Click to see in full size:

Doclet API provides any description as a collections of instances of the interface:
com.sun.source.doctree.DocTree
which for program elements is obtained by calling the method:
com.sun.source.util.DocTrees.​getDocCommentTree(Element)
The DocTree interface is extended by a number of other interfaces found in com.sun.source.doctree package, which represent everything the doc-comment is made of, like:
  • pieces of text
  • HTML elements and their attributes
  • inline tags
Some of those things (like inline tags) may have own descriptions (collections of DocTree objects) attached to them, which are obtainable through the specific methods of the corresponding interfaces.

Doclet DSM maps instances of DocTree interface onto 'DTree' DSM elements, which are obtained from other DSM elements

  • either as their children
  • or via their specific DSM attributes returning DTree-element references
This stock-section processes such a collection of DocTree objects (representing a description) returned by the Doclet API by iterating through the corresponding 'DTree' DSM elements, which those objects are mapped on, and processing each of them according to its type (click to see in full size):

Here is a series of commented screenshots explaining how the rendering of {@code} / {@literal} inline tags works. Click to view all screenshots:

Template Location:

{flexdoc-javadoc}/templates/classic/lib/description/text.tpl

Called From:

overview.tpl, module.tpl, package.tpl, class.tpl, deprecated-list.tpl, index-letter.tpl, serialized-form.tpl, doc-reference.tpl, block-tags.tpl, summary.tpl

Calls:

doc-reference.tpl

doc-reference.tpl

This template generates the hyperlinked text representation for Java language element references found in Java doc-comment tags like @see or {@link}, e.g.:
module/package.class#field
module/package.class#method(arg-types)
Doclet API represents such references with instances of the interface
com.sun.source.doctree.ReferenceTree
which FlexDoc/Javadoc maps onto 'DTreeReference' DSM elements. So, the job of this template is to render DTreeReference elements.

Here is the template's root section block, which contains a single Area Section with a Call Stock-Section Control that generates everything. Click to see in full size:

Here is a series of commented screenshots explaining how this template works. Click to view all screenshots:

Template Location:

{flexdoc-javadoc}/templates/classic/lib/description/doc-reference.tpl

Called From:

block-tags.tpl, serialized-form.tpl, text.tpl

Calls:

classLinkTitle.tpl, className.tpl, text.tpl

block-tags.tpl

This template generates description sections typically produced from block-tags specified in doc-comments (of a Java program element), like shown on the following screenshot:

Here is the template's root section block (click to see in full size):

It consists of the main Element Iterator specified to iterate 'DTreeBlockTag' DSM elements that represent block-tags obtained from Java doc-comments. Additionally, some extra items are injected into the iteration scope to be added to the lists generated from the real block-tags of certain types (e.g. @see), so that everything looked as single lists under the same headings. Those extra items are framed as special '#PseudoBlockTag' DSM elements, which come not from the Doclet DSM, but created during the call of block-tags.tpl and passed to it via the 'pseudoBlockTags' template parameter. Both types of elements appear to the Element Iterator the same, which allows processing them together. Here is how the obtaining of all those elements is specified:

Once the DSM elements (representing the tags) to iterate have been collected, they are filtered to leave only tags selected to be documented for the given Java program element type (see the parameter group: “Include | Tag”):

Then, the tags are sorted by their group and ordering numbers:

The tags of the same type (i.e. with the same tag name) have the same ordering number. So, they gather into continues sequences.

At last, the result collection of tags (i.e. DSM elements representing them) is broken into to the groups of tags of the same type:

The main Element Iterator actually iterates those groups (or, rather the first elements from each group). All group elements are accessible via the property iterator.groupElements within a FlexQuery-expression.

The sections inside the main iterator process different types of tags. For instance, here you see the processing of tags: @author, @since, @version. The nested Element Iterator iterates through the group of all tags of one of those types (for instance, there may be multiple @author tags in the same doc-comment) and prints their content separated with commas under a single heading specific for this particular tag type:

And here is how that nested iterator is specified:

Template Location:

{flexdoc-javadoc}/templates/classic/lib/description/block-tags.tpl

Called From:

serialized-form.tpl, text.tpl, block-tags.tpl

Calls:

className.tpl, text.tpl

summary.tpl

This template generates the summary description of a Java program element, which is used in summary tables (click to see in full size):

Such a description typically comes from the first sentence of the full description. It is provided by the Doclet API method
com.sun.source.doctree.DocCommentTree.getFirstSentence()
which is mapped in Doclet DSM to the element/attribute:
DTreeComment/@firstSentence
In case of methods, if own description is absent, it is looked also by the overridden and implemented methods.

Additionally, when the program element is deprecated, the message about that is displayed first.

Template Location:

{flexdoc-javadoc}/templates/classic/lib/description/summary.tpl

Called From:

module.tpl, class.tpl, package-summary.tpl, class-summary.tpl, package-use.tpl, class-use.tpl, index-letter.tpl, module-summary.tpl

Calls:

annotations.tpl, className.tpl, text.tpl, doc-reference.tpl

doc-file-html.tpl

This template inserts in the documentation stand-alone description files like this one (click on the screenshot to see the real HTML):

The actual content of every such a document comes from a corresponding HTML file found in doc-files directory by a package/module. That source HTML is parsed (using Doclet API) and represented in Doclet DSM as a 'DocFile' DSM elements shown here (click to enlarge):

The DocFile element is passed to this template, which just reproduces the original file content, adding to it the navigation bars to it at the top and bottom. Here is the template's root section block (click to see in full size):

And this is how its main Element Iterator (shown selected on the template screenshot) is specified:

Besides the primary content of the source HTML file (enclosed between <body> tags), there is also the HTML's head (enclosed between <head> tags), which equally needs to be reproduced in the result document. That is done as shown on the next screenshots.

Similar to the template root section block, the content of the HTML head is iterated in the Template Init Expression (the left screenshot), but now using the means of FlexQuery functions, and accumulated in the 'head_content' variable. Also, the HTML title is retrieved during that. Further, both title and the head content are passed into the expressions that provide the actual title and head of the result HTML document (the top and bottom screenshots on the right):

Template Location:

{flexdoc-javadoc}/templates/classic/lib/description/doc-file-html.tpl

Called From:

module.tpl, package.tpl

Calls:

navbar.tpl, navbar-bottom.tpl