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):
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):
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.![]()
The frameset structure is defined in the form of a tree. The condition icon![]()
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:
Using an element map, it is possible. The element map is created as the following:
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”.
The next screenshot shows an HTML file produced by this template:
The next screenshot shows an HTML document produced by this template:![]()
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):![]()
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:![]()
{@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.
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:
You can easily suppress it by disabling the Area Section, as shown on the screenshot:
(Or replace it with something of your own.)![]()
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/templates/javadoc/demo/html/package-list
(which is a part of a demo framed HTML documentation).