Products         Customers         News         Downloads         Licensing         Shop    

 DocFlex Technology
Overview
Features
Documentation
 DocFlex/XML
Overview
Features
Documentation
XSDDoc
WSDLDoc
Integrations
Bundles
 DocFlex/Javadoc
Overview
Documentation
Basic Templates
Templates
Parameters
JavadocPro
Examples
Tutorials
 DocFlex/Together
Overview
Examples
Basic Templates
Documentation
Tutorials
 Try
Downloads
Registration
Trial License
 Buy
Licensing
Shop
 Company
News
Products
Customers
About Us
Imprint
Legal
Contact
Links
 

DocFlex/Javadoc - Basic Templates - Template Details

  1. Main Templates
  2. Initialization Subtemplate
  3. Detail Subtemplates
  4. Fragment Subtemplates
  5. Reference List Subtemplates

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

What it generates

The following screenshots show pages of an RTF demo documentation generated with PlainDoc.tpl (click to see in full size):
RTF demo: javax.swing.text.Document RTF demo: javax.swing.text.Document RTF demo: javax.swing.text.Document
However, this template can equally produce single-file HTML documentation. The following screenshot shows such an HTML generated from the whole javax.swing.text package (click to download a zip-archive of this demo doc):
Single-file HTML documentation

Template screenshot

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

FramedDoc.tpl

This is the second main template provided in downloads.

What it generates

The FramedDoc.tpl template is a frameset template, which means 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 generator. However, once implementations of new format arrive in next DocFlex versions, it is quite possible that the concept of interactive frames could be extended to other formats as well (e.g. PDF).

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

Framed HTML documentation

Template screenshot

Here is how FramedDoc.tpl looks when loaded in the Template Designer:
FramedDoc.tpl
As you can see, this template consists mainly of calls of subtemplates, which generate the documents displayed in the frame windows. The main section block does not produce any output by itself.

Defintion of frameset

Besides the main section block, the next important thing contained in FramedDoc.tpl is the frameset structure that is specified in the template properties:
FramedDoc.tpl - Frameset Structure
The frameset structure is defined in the form of a tree. The condition icon 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.

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

  1. The list of all classes in the project
  2. For a given class -- the list of all interfaces it directly implements
  3. For a given class -- its superclass
  4. 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:

  1. All classes in the project are iterated.
  2. For each class (according to the items 2-4 in the list above), we find all interfaces that class directly or indirectly implements.
  3. 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:
init.tpl
preparing an element hashmap
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.

You can find a lot more information about Element Maps, Location Rules and the functions to work with them at: Template Designer | Help | Assistant... | Functions | By Category | “Elements / Attributes” | “Element Maps” and “Location Paths & Rules”.

3.  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:
  1. when called from PlainDoc.tpl, it generates a big sections of the single-file documentation;
  2. 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.
overview-summary.tpl

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

Overview summary

package-summary.tpl

This template generates a package overview (i.e. description, tags and summary tables of contained classes):
package-summary.tpl
The next screenshot shows an HTML document produced by this template:
Package summary

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:
class.tpl
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):
Class documentation   Interface documentation   Enum documentation   Annotation Type documentation

4.  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:
annotations of a class
nested annotations of a method
Here is the annotations.tpl template itself when loaded in the Template Designer (click to see a large screenshot):
annotations.tpl
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):

annotations.tpl - “Annotation” stock-section
This one reproduces an annotation's element value:
annotations.tpl - “Annotation Value” stock-section

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

inline-tag.tpl (collapsed)
Each section catches and processes a specific inline tag. On the following screenshot, those sections are shown when expanded:
inline-tag.tpl (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:

see-link.tpl (collapsed)
see-link.tpl (expanded)

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:

about.tpl
(Or replace it with something of your own.)

5.  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).
overview-frame.tpl

all-classes-frame.tpl

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

package-frame.tpl

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

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:

package-list.tpl
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:
package-list.tpl - package iterator
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/docflex-javadoc/templates/javadoc/demo/html/package-list
(which is a part of a demo framed HTML documentation).

Copyright© 2003-2014 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.