JavadocClassic, Version 3.0

What is JavadocClassic?
Content Files
Technical Requirements
Licensing
Installation
Running JavadocClassic
Getting Help
Change Log

What is JavadocClassic?

«JavadocClassic» is a template application (template set) for FlexDoc/Javadoc that implements a powerful Java API documentation generator with the following features:

Generation of framed HTML documentation similar to that produced by the Standard Doclet with the classical look&feel
The same documentation as single-file in HTML and RTF formats
Full support of Java 9 language features
Generating single documentation for either non-modular, single-module or multi-module Java projects
Filtering of classes and members by tags/annotations
Unlimited customizations, including through custom CSS styles and modifying templates themselves

JavadocClassic template set provides two main templates:

FramedDoc.tpl – to generate framed multi-file HTML documentation
SingleDoc.tpl – to generate single-file HTML and RTF documentation

Main template is the one, which can be specified for interpretation directly to the generator (either with -template option on the Javadoc command line or in the Doclet GUI Dialog). Effectively, each main template represents a separate documentation generator.

JavadocClassic template set is included in FlexDoc/Javadoc software archive and found in the directory: {flexdoc-javadoc}/templates/classic/

{flexdoc-javadoc} is a designation of your FlexDoc/Javadoc installation directory, e.g.: C:\flexdoc-javadoc-2.0\

Content Files

The following files power JavadocClassic (or are related to it):

File / Directory	Description
`README.html`	this file
`FramedDoc.tpl`	The main template to generate framed HTML documentation.
`SingleDoc.tpl`	The main template to generate single-file documentation (in HTML or RTF format).
`help/`	The descriptions of parameters of both main templates; used by the Parameter Inspector.
`lib/`	The directory containing all subtemplates (and icon files) that power the JavadocClassic template application.
`doclet9.dsmtype`	The configuration file that defines the `'doclet9'` DSM Type, on which the JavadocClassic template set is based. Although the Doclet DSM itself is defined in the implementation of Doclet DSM Driver, this configuration file allows you to extend it with some custom element types used in the template application.
`dsmtype/CustomElements.json`	This file is referenced from `doclet9.dsmtype` and contains the definitions of custom element types used in JavadocClassic template set. Custom Elements allow you to create structured chunks of data that look the same as ordinary DSM elements coming from the main data source (i.e. Doclet API). Thereby, they can be manipulated together with the ordinary elements and using the same template functionality (e.g. iterated, sorted, grouped etc).
`css/`	CSS stylesheets that may be used with JavadocClassic while generating of HTML documentation:
`stylesheet_ext.css`	Defines CSS styles used in descriptions of JDK 17 API (see Using extra CSS stylesheets)
`azure-theme_FramedDoc.css`	An alternative CSS skin for framed HTML to apply with FramedDoc.tpl (see Using “azure-theme” stylesheets)
`azure-theme_SingleDoc.css`	The same for single-file HTML to apply with SingleDoc.tpl
`azure-theme_ext.css`	The same CSS rules as in `stylesheet_ext.css` however adapted for “azure-theme” skin.
`TitlePageDemo/`	A custom title page demo. See: Trying custom title page demo

Note: All files and directories are located in JavadocClassic home directory: {flexdoc-javadoc}/templates/classic/

Technical Requirements

JavadocClassic is just a set of templates (which are plain-text files). To execute it, you always need the template processor (generator) built into FlexDoc Doclet.

Please note that some general functionality (i.e. template language) used in a particular version of JavadocClassic may be available only since the specific version of FlexDoc/Javadoc. For instance, JavadocClassic version 3.0 requires FlexDoc/Javadoc version 2.0 or later.

Licensing

JavadocClassic is covered by the same license as the whole «FlexDoc/Javadoc» license, which may be one of three types:

License Type Description

License Type	Description
Demo License	Once you have downloaded FlexDoc/Javadoc archive, you can run JavadocClassic immediately and see what it is. You don't need to request any trial and register anywhere! By default, everything will work in demo mode. It means that all your input Java classes will be fully processed, however fully documented will be only limited number of them. What exactly the demo limits are depends on a particular main template (as well as some metrics). If those limits are not reached, you will get the complete documentation. Otherwise, some content will be omitted and the message included saying which limits were exceeded. Anyway, the result documentation will be minimally distorted, to allow you to evaluate how everything will look under the full license. Any documentation generated in demo mode is yours. You may use it for free as you wish. See also: {flexdoc-javadoc}/LICENSE.html \| Demo License
Full License	The full (or commercial) “FlexDoc/Javadoc” license unlocks all functionality implemented in JavadocClassic template set. In particular, you will be able to: Generate complete documentation by any your Java project (with any number of Java classes) in all supported output formats. Use FramedDoc.tpl main template to generate framed HTML documentation. Use SingleDoc.tpl main template to generate single-file documentation (HTML or RTF). Use all parameters controlling JavadocClassic templates to customize the generated documentation within a great range of possibilities (including filtering classes/members by tags/annotations). Format your Java comments with HTML tags and reproduce that formatting both in HTML and RTF output. Insert images in your documentation through both templates and HTML `<img>` tags (supported both in HTML and RTF output). Run any your custom templates derived from JavadocClassic. Since the “FlexDoc/Javadoc” license is also the «SDK license», it will allow you additionally: To use Template Designer to create/modify any FlexDoc/Javadoc templates (including JavadocClassic). To apply custom CSS styles. See also: {flexdoc-javadoc}/LICENSE.html \| Full License
Trial License	The trial license is functionally the same as the full one. The difference is that: It is valid only during the limited period of time. Any output documents generated under a trial license will be specifically distorted by replacing some letters with shade ('░') characters (as well as contain special messages). Such documents may be used only for evaluation of FlexDoc/Javadoc software. Any other use is prohibited! You can obtain a trial license by this link: http://www.flexdoc.xyz/trial/?pid=flexdoc-javadoc See also: {flexdoc-javadoc}/LICENSE.html \| Trial License

Demo License

Once you have downloaded FlexDoc/Javadoc archive, you can run JavadocClassic immediately and see what it is. You don't need to request any trial and register anywhere!

By default, everything will work in demo mode. It means that all your input Java classes will be fully processed, however fully documented will be only limited number of them. What exactly the demo limits are depends on a particular main template (as well as some metrics).

If those limits are not reached, you will get the complete documentation. Otherwise, some content will be omitted and the message included saying which limits were exceeded. Anyway, the result documentation will be minimally distorted, to allow you to evaluate how everything will look under the full license. Any documentation generated in demo mode is yours. You may use it for free as you wish.

Full License

The full (or commercial) “FlexDoc/Javadoc” license unlocks all functionality implemented in JavadocClassic template set. In particular, you will be able to:

Generate complete documentation by any your Java project (with any number of Java classes) in all supported output formats.
Use FramedDoc.tpl main template to generate framed HTML documentation.
Use SingleDoc.tpl main template to generate single-file documentation (HTML or RTF).
Use all parameters controlling JavadocClassic templates to customize the generated documentation within a great range of possibilities (including filtering classes/members by tags/annotations).
Format your Java comments with HTML tags and reproduce that formatting both in HTML and RTF output.
Insert images in your documentation through both templates and HTML <img> tags (supported both in HTML and RTF output).
Run any your custom templates derived from JavadocClassic.

Since the “FlexDoc/Javadoc” license is also the «SDK license», it will allow you additionally:

To use Template Designer to create/modify any FlexDoc/Javadoc templates (including JavadocClassic).
To apply custom CSS styles.

Trial License

The trial license is functionally the same as the full one. The difference is that:

It is valid only during the limited period of time.
Any output documents generated under a trial license will be specifically distorted by replacing some letters with shade ('░') characters (as well as contain special messages). Such documents may be used only for evaluation of FlexDoc/Javadoc software. Any other use is prohibited!

You can obtain a trial license by this link: http://www.flexdoc.xyz/trial/?pid=flexdoc-javadoc

Installation

Since JavadocClassic is a part of FlexDoc/Javadoc software, you don't need to do anything special to install it. Once you have installed FlexDoc/Javadoc, you will find JavadocClassic in the directory:

{flexdoc-javadoc}/templates/classic/

Actually, JavadocClassic template application is quite autonomous. You can copy/move (or rename) the 'classic/' directory to any other location and run the templates directly from there. This may be particularly useful when you want to modify something in the original templates and derive your own version of JavadocClassic.

Running JavadocClassic

Generating framed HTML

To generate Java API documentation, please follow these steps:

Edit {flexdoc-javadoc}/bin/generator-modular.bat
to specify the 'JDK_HOME' variable according to the location of JDK 11 (or later) installed on your system.
If you don't have the necessary Java version installed on your system, you can freely download and install the Java Development Kit (JDK) from either:
- Oracle Java Technology web-site: https://www.oracle.com/java/technologies/
- OpenJDK web-site: https://jdk.java.net
In the bottom line, you can also specify the location of your Java packages/classes to document.
By default, it is specified for a demo Java project included in FlexDoc/Javadoc: {flexdoc-javadoc}/demo/modular
Run generator-modular.bat. You will see the generator dialog.
While running JavadocClassic templates for large Java projects, the template interpreter may require a lot of memory. The lack of memory may considerably slow down the generation (or even cause the OutOfMemory exception)! To avoid this, make sure the maximum heap size available for JVM is 1024Mb or more (e.g. Javadoc option -J-Xmx1024m sets the maximum heap size to 1024Mb).
In «Template» field, select FramedDoc.tpl template.
You can choose this template from {flexdoc-javadoc}/templates/classic/ directory using File Chooser.
In «Output format» field, select HTML format.
The FramedDoc.tpl main template can generate only framed HTML documentation!
Click «Run» button to start the generation.

Then, the generator enters into the estimation phase. Lots of processing is being done during that, however, you will see only "Scanning data source, please wait..." message on the progress bar. On large Java projects, this phase may take some time. Please wait! After that, the generator passes into the generation phase. The progress bar will show what's being generated.
You can stop the generator at any time during any phase by clicking «Cancel» button.

Generating single-file RTF / HTML

To generate single-file RTF or HTML documentation, everything is the same as in the case of framed HTML, except that

In «Template» field, select SingleDoc.tpl template.
In «Output format» field, select HTML or HTML format correspondingly – both will work.

Using extra CSS stylesheets

Since all structure and styling of the generated documentation is defined in templates, the Template Processor / HTML Output Generator fully controls the generation of any relevant CSS by itself.

There is a way to hack into that by feeding to the generator some custom CSS rules associated with particular formatting styles defined in templates. See: Using “azure-theme” stylesheets

However, any doc-comments specified in your Java code are fed directly into the generated HTML output. So, you can use in them any your special CSS classes, which will be beyond the influence of FlexDoc.

To provide such custom CSS classes used in your doc-comments, on the step of selecting HTML format, click «Options» button and in the HTML Options dialog that appears, specify:

Output | CSS | Extra CSS files = <CSS file list>

The one or several CSS files specified with this option should contain any special CSS rules you use to style your descriptions as doc-comments in your Java sources. Those CSS files will be copied into the documentation destination (associated files) directory, and links to them are inserted in every generated HTML document, e.g.:

<link rel="stylesheet" type="text/css" href="../custom.css">

The 'stylesheet_ext.css' file provided with JavadocClassic:

{flexdoc-javadoc}/templates/classic/css/stylesheet_ext.css

is such an extra stylesheet that defines the CSS classes widely used in doc-comments found in Java sources of recent JDK API (e.g. JDK 17) as well as other things. This includes:

Indicator icon for external links – applies to all external hyperlinks, not only those in descriptions.
Styles for user-provided tables: borderless, plain, striped.
The same is supported also for RTF output using formatting styles specified in SingleDoc.tpl. See also:
- {flexdoc-javadoc}/docs | FlexDoc/Javadoc | Features | Formatting | Using formatting styles to render CSS classes
- {flexdoc-javadoc}/docs | FlexDoc/Javadoc | JavadocClassic | Templates | Main Templates | SingleDoc.tpl | Using styles to render CSS classes

Using “azure-theme” stylesheets

JavadocClassic comes with demo CSS style sheets that implement an alternative skin (look & feel) for HTML documentation. You can find them in {flexdoc-javadoc}/templates/classic/css/ directory:

azure-theme_FramedDoc.css is applicable with FramedDoc.tpl
azure-theme_SingleDoc.css is applicable with SingleDoc.tpl

You can use these CSS files also as a base for your own customizations.

To apply azure-theme_FramedDoc.css, please follow the same steps as described in Running JavadocClassic. On the step of selecting HTML format, click «Options» button and in the HTML Options dialog, which should appear, specify:

Output | CSS | Generate named rules = all
Output | CSS | Generate named rules | Custom rules file = templates/classic/css/azure-theme_FramedDoc.css
Output | CSS | Extra CSS files = templates/classic/css/azure-theme_ext.css

Then, close that dialog by <OK> and proceed with other steps.

Notes:

The possibility to use any CSS stylesheets is available only under the «FlexDoc/Javadoc» license.
For more details about custom CSS, please see: {flexdoc-javadoc}/docs | FlexDoc.XYZ | Documentation | Usage of CSS in generated HTML

Trying custom title page demo

In the directory:

{flexdoc-javadoc}/templates/classic/TitlePageDemo/

you can find a template:

custom-title-page.tpl

which is a custom replacement for the standard lib/title-page.tpl template that generates the Title Page in single-file documentation.

This template was created on a request of a customer to demonstrate how to add a static image on the title page (e.g. logotype) inside a complex table structure with multi-row spanning cells.

That template is called from SingleDoc.tpl, however, the call is disabled. To enable it:

Open SingleDoc.tpl in the Template Designer.
Find «Call Template 'TitlePageDemo\custom-title-page.tpl'» section and click right-mouse over it. In the local menu toggle «Disabled» item.
The same way disable «Call Template 'lib\title-page.tpl'» section that calls the standard version of title page template.
Save the edited SingleDoc.tpl. Now, you can run it.

Getting Help

The most detailed and up-to-date information about JavadocClassic can be found on its homepage: www.flexdoc.xyz/flexdoc-javadoc/classic/
General support information: www.flexdoc.xyz/support/
User support forum (free to everyone): http://www.flexdoc.xyz/forum/
You can also send any your questions by e-mail to: support@flexdoc.xyz

Change Log

Version 3.0

The entire template set has been fully reworked and switched to the new Doclet DSM that represents the new Doclet API (introduced since Java 9).
Thereby, JavadocClassic works now with all JDK versions starting from Java 11.
The template set has been extended to document Java modules and any references to them.
The documenting of old non-modular Java projects is equally fully supported (through the same new Doclet API).
Rendering of CSS styles used in doc-comments also in RTF output. See: Using extra CSS stylesheets.

Version 2.0

JavadocClassic is the further development of the previous «JavadocPro» template set (available since DocFlex/Javadoc 1.6.0). Hence, it starts from the version number 2.0 already.

Here is the list of what has changed:

Upgrade with all new template language features introduced since FlexDoc/Javadoc 1.7.0
Support of styling the generated HTML documentation with custom CSS.
Since FlexDoc/Javadoc 1.7.0, it became possible to define template formatting styles for tables, table rows, table cells and horizontal rules. That, along with paragraph and character styles existed before, allowed switching all documentation formatting programmed in JavadocClassic templates to be specified only through styles. The benefit of that is that template formatting styles can be automatically translated into named CSS rules, which in turn can be substituted by the custom ones. So, now you can substantially change how your documentation looks only by applying your custom CSS stylesheet during the generation. See also: Using «azure-theme» stylesheets.
Support of custom taglets