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

  1. Overview
  2. What you can generate with it
  3. Template Set Overview
  4. Licensing
  5. Tips

1.  Overview

The Basic Template Set is an early version of standard templates provided with DocFlex/Javadoc. Currently, it is superseded by “JavadocPro” template set. However, it is still included in both editions of DocFlex/Javadoc because it is simpler and requires less licensing (basically, it is free).

Using it, you can generate:

  • HTML JavaDoc (both framed and single file) with basic content: project overview, package summaries, class details.
  • RTF JavaDoc
The Basic Template Set consists of just 14 templates subdivided into two categories:
  1. The main templates, which are designed to produce finished documentation and should be specified on the Javadoc command line or in the generator dialog. The main templates are located in 'templates/javadoc/' directory of the DocFlex/Javadoc installation.
  2. 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/javadoc/lib/' directory of the DocFlex/Javadoc installation.

2.  What you can generate with it

HTML Output

Framed HTML Documentation

Multi-framed HTML documentation can be generated with FramedDoc.tpl main template.
Framed HTML documentation

Single File HTML Documentation

The same entire documentation (above) can be equally generated as a single HTML file using PlainDoc.tpl main template.
Single-file HTML documentation

RTF Output

Using PlainDoc.tpl main template, it is possible not only to generate a single file HTML. Simply, by switch the generator output format to “RTF”, the same template will produce a highest quality RTF file!
RTF demo: javax.swing.text.Document RTF demo: javax.swing.text.Document RTF demo: javax.swing.text.Document

3.  Template Set Overview

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.

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

Template Description Called From
init.tpl creates element maps PlainDoc.tpl, FramedDoc.tpl
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
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
inline-tag.tpl processes most of the inline tags class.tpl, overview-summary.tpl, package-summary.tpl
see-link.tpl processes a user-defined cross-reference to related documentation class.tpl, inline-tag.tpl, overview-summary.tpl, package-summary.tpl
about.tpl prints the “about” information at the bottom of most of documents PlainDoc.tplclass.tpl, overview-summary.tpl, package-summary.tpl
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

Template Parameters

Template parameters control the template set. In effect, they serve the role of command-line options provided by the Standard Doclet.

For further details, please see: DocFlex/Javadoc | Basic Templates | Parameters

4.  Licensing

The Basic Template Set is free:
  • You can generate with it any documentation (in any supported format) and use it without limitation.
  • The same is extended to the templates derived from Basic Template Set (if you modify something). However, the modification itself must be done under an appropriate “DocFlex/Javadoc” license that covers the Template Designer included in the Full Edition.
See also: Licensing of Templates | Basic Templates

5.  Tips

Omitting package qualifiers

Since DocFlex/Javadoc, version 1.1, the provided basic templates include two additional parameters to suppress appearing package qualifiers in the generated documentation in such places like method parameters, field types and so on:
  1. Omit package qualifiers started with
  2. Omit all package qualifiers
See the full description of those parameters at Basic Templates | Parameters | Descriptions of parameters.

Excluding classes/methods/fields with a custom tag/annotation

Since version 1.3, there is a new template parameter "Exclude by tags" (exclude.byTags), which since v1.5.1 has been split into several ones. Those parameters can be used to exclude from the generated documentation classes, fields and methods with specified tags. See the parameter description for more details.

Since version 1.5.2, to that was added a possibility to exclude everything by annotations. See "Exclude by annotations" parameter group (exclude.byAnns.*). Annotations are more cumbersome to use for that purpose. But they can be retained in the compiled classes. So the exclusion will work even when no corresponding Java source code is found on Javadoc source path.

Migrating to a new version of basic templates

This section is addressed to those our users who have a full commercial or academic license for DocFlex/Javadoc.

Suppose, some time ago you modified the basic templates according to your needs and since then have been (happily) using them. Now, you come to this web-site and notice that the latest version of DocFlex/Javadoc supports a host of new features, which might be interesting to you too (for instance, the full support of Java 5.0).

Of course, you can run your old templates with the new DocFlex Doclet version. But this won't make those new features automatically available to you. First, they must be applied in templates, which are the actual programs that generate everything. (See About DocFlex/Javadoc | Key Features | Template-driven doclet architecture)

So, now you need to migrate to the new basic template set and copy to there or replicate all your specific changes necessary for your work. What is the best way to do this?

The safest way would be to replicate all your changes on the new templates.

You may try to mix your old templates with the new ones. But keep in mind that we constantly change something from the version to version.

Some subtemplates depend on other templates that call them. Basically, there are two such dependencies:

  1. The template parameters
  2. The element maps
Especially this concerns element maps, which are a special kind of hash-tables adapted for DSM elements. Element maps help to resolve some very complex data-mining queries.

The basic template set is organized so that during the first steps each main template calls the init.tpl subtemplate, whose job is to create the element maps. All element maps are global. Further, they are used in many locations across the template set (especially, in class.tpl).

If the structure of some element maps is different from what is expected and used by a template, that template will work incorrectly (or not work at all)!

Note:   Since v1.5.6, all basic templates also include the version number of the DocFlex/Javadoc release to which the particular template set belongs. This may help you to quickly recognize if you have inadvertently mixed the templates from different versions and because of this now experience errors and wrong working of your template application.

You can find the version in the 'APP_VER=...' line of each template as well as in the Template Designer | Template Properties Dialog | General tab | Template Application tab.

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