FlexDoc/Javadoc - JavadocClassic

JavadocClassic is included in FlexDoc/Javadoc archive, which is ready for downloads now!

  1. What is JavadocClassic?
  2. What you can generate with it
  3. What is processed/documented
  4. Template Set Overview
  5. Possibility of unlimited customizations
  6. Getting Started
  7. Licensing

1. What is JavadocClassic?

“JavadocClassic” is a template set for FlexDoc/Javadoc that implements a powerful Java API documentation generator with the following features:

2. What you can generate with it

Framed HTML Documentation

Using FramedDoc.tpl main template, you can generate a complete Java Documentation with the look&feel similar to classical one, however all content almost identical to what is generated now by Java 17 Javadoc.

Click on a screenshot to view a demo HTML JavaDoc (generated from Open JDK 17 source code):

Jumping directly to a particular detail Jumping directly to a particular detail

The following functionality is fully supported:

Single-File Documentation

SingleDoc.tpl is another main template that generates the entire JavaDoc as a single file/document, which can be in any supported output formats (primarily HTML and RTF).

HTML Documentation

With SingleDoc.tpl main template and the output format set to «HTML», you can generate the entire JavaDoc as a single-file HTML:

RTF Documentation

Using SingleDoc.tpl main template with the output format set to «RTF», you can generate single-file RTF JavaDoc. It is built of the same basic blocks as the framed HTML documentation (which are actually generated by the same subtemplates) with a few additional features.

This includes:

These screenshots show pages of an RTF documentation generated by several JDK Source classes (click to see in full size):

See also FlexDoc/Javadoc | JavadocClassic | Demo | RTF Demo for more details about that demo RTF and other screenshots.

PDF Documentation

FlexDoc/Javadoc currently generates no PDF directly. However, you can produce quite decent PDF from RTF using some converters.

Here is a PDF JavaDoc generated in that way (click on the screenshot to see/download the PDF file):

This PDF has been produced by ASPOSE RTF to PDF Converter

3. What is processed/documented

All Java 9 language features

Everything that standard Java 17 Javadoc does, including the full support of:

Filtering classes/members by tags/annotations

You can both: This will equally work for all types of generated documentation.

For details about what excluding of classes/members actually means, please see the descriptions of filtering parameters: JavadocClassic | Parameters | Filter Classes & Members

HTML tags in Java comments

Javadoc assumes that initial descriptions of Java packages, classes, members, parameters etc. are stored within Java sources themselves in the form of specially formatted comments. Those comments may contain also user HTML tags (markup) so that in the generated documentation the descriptions appear with various font styles (italic, bold) and include lists, tables, images, hyperlinks etc.
HTML output
In case of HTML output, little needs to be done for rendering such user HTML tags – just passing them on into the generated HTML along with the description text.
Sometimes, user HTML markup may contain syntax errors (e.g. missing closing tags), which can heavily distort the generated HTML. FlexDoc HTML generator is able to fix many such errors. You just need to specify “Text | Render embedded HTML | Fix markup” option, e.g. on command line:
-o html.text.renderEmbeddedHTML.fixMarkup=true
or in HTML Option Inspector.
RTF output
In case of RTF output, the embedded HTML markup needs to be fully parsed and interpreted with the corresponding formatting features available in RTF. That is supported by FlexDoc RTF generator for almost all HTML tags practically usable in documentation comments (including insertion of images).

There is also an RTF option for this: “Text | Render embedded HTML”, which is selected by default.

On the following screenshots you can see pages of an RTF JavaDoc generated from Java sources laden with lots of HTML markup (click to enlarge):

See Also: FlexDoc/Javadoc | Features | Formatting | Rendering of HTML markup in Java comments

4. Template Set Overview

The entire “JavadocClassic” template set currently consists of 40 templates, which include: For detailed information about each template, please see: FlexDoc/Javadoc | JavadocClassic | Templates

Main Templates

Main templates are those that can be specified for interpretation directly either with -template option on the Javadoc command line or in the Doclet GUI. Each main template effectively represents a separate documentation generator.

Main Template Summary
FramedDoc.tpl Generates framed HTML Java API documentation identical to the classic JavaDoc.
SingleDoc.tpl Generates single-file JavaDoc (both RTF and HTML).

Subtemplates

Besides the main templates, there are many other templates (called subtemplates) that are used internally. Those templates work as procedures invoked from the main templates as well as from each other.

Subtemplate Summary
init.tpl This template produces no output. Instead, it is called only once from either SingleDoc.tpl or FramedDoc.tpl main templates before any other processing starts. The template's job is to create element maps that are critical for the working of other templates.
Basic Content Subtemplates Generate pages or sections that provide primary information about the Java project
overview.tpl Generates the documentation «Overview» page/section (an equivalent of the 'overview-summary.html' file generated by the Standard Doclet).
module.tpl Generates a «Module Documentation» page/section for every Java module being documented (an equivalent of the 'module-summary.html' file generated by the Standard Doclet).
package.tpl Generates a «Package Documentation» page/section for every Java package being documented (an equivalent of the 'package-summary.html' file generated by the Standard Doclet), which includes package description, tags and summary tables of contained classes.
class.tpl Generates a «Class Documentation» page/section for a class/interface/enum or an annotation type. The class documentation may include the class description, various reference lists about it, as well as the details of all documented members of that class (except nested classes). This provides the bulk of the whole Java API documentation.
Cross-Reference Page Subtemplates Generate pages of framed HTML documentation that help to quickly find the necessary information
package-summary.tpl Generate a package summary table included in the general Overview (produced overview.tpl template).
class-summary.tpl Generates the «All Classes Summary» page, which is loaded when clicking on «All Classes» item in the navigation bar in framed HTML documentation.
package-use.tpl Generates a «Use» page for each documented package. The page describes which packages and classes use any API of the given package.
class-use.tpl Generates a «Use» page for each documented class. The page describes which packages, classes, methods, constructors and fields use any API of the given class.
class-tree.tpl Generates «class/interface hierarchy» pages. These are the pages you reach using the «Tree» button in the navigation bar.
deprecated-list.tpl Generates the «deprecated API» page ('deprecated-list.html' file), which contains the list of deprecated APIs, and the «Deprecated» link in the navigation bar to that page.
index-all.tpl Generates a single «index» page ('index-all.html' file). It is used when no splitting of the index into multiple files has been specified.
index-letter.tpl Generates index for a particular letter either a section of the whole index file (i.e. 'index-all.html' generated by index-all.tpl) or a corresponding separate index page ('index-*.html').
serialized-form.tpl This template generates the «serialized form» page, which provides information about serializable and externalizable classes.
constant-values.tpl This template generates the «constant field values» page ('constant-values.html' file), which lists the static final fields and their values.
Support File Subtemplates Generate files that help to navigate the framed HTML documentation and connect to it
help-doc.tpl Generates the «Help» page. This is the page you reach using the «Help» button in the navigation bar.
overview-frame.tpl Generates the primary navigation page, which includes the lists all packages and other primary links. It is used in the upper-left "Overview" frame.
allclasses-frame.tpl Generates a navigation page with the list of all documented classes. It is loaded in the lower-left "List" frame.
module-frame.tpl Generates a separate navigation page for each documented module, which is loaded into the lower-left "List" frame on clicking on the corresponding module in the "Overview" frame.
package-frame.tpl Generates a separate navigation page for each documented package, which is loaded into the lower-left "List" frame on clicking on the corresponding package in the "Overview" frame.
element-list.tpl Generates an 'element-list' file, which is a plain-text file that lists the names of all documented modules/packages (or those containing the documented classes). It is used by Javadoc to generate hyperlinks from another Java API documentation to this one.
Section Subtemplates Generate separate (relatively large) sections of the documentation (however, never separate files)
module-summary.tpl Generate a package summary table included in the general Overview (produced overview.tpl template).
title-page.tpl Generates the «Title Page» (which will be the front page of the RTF documentation).
TOC.tpl Generates the «Table Of Contents» of the documentation.
Fragment Subtemplates Called from other templates to generate small (but frequent) fragments of the documentation
annotations.tpl Generates the list of annotations of a module, package, class, member, type or type/constructor/method parameter, along with all related hyperlinks.
className.tpl Generates the name of a Java class and the hyperlink from it to the class documentation.
classLinkTitle.tpl Generate the title (tooltip) for a class hyperlink.
type.tpl Generates the text representation of a Java type the same as in Java code and with all relevant hyperlinks.
typeArguments.tpl Generates the representation of type arguments ot type parameters (their declaration).
navbar.tpl Generates all navigation bars found the framed HTML documentation.
navbar-bottom.tpl Generates overall footer of each detail page in framed HTML documentation including footer navigation bar, bottom text and «About» section.
about.tpl Adds «About» section at the bottom of each separate output document. It displays the information about FlexDoc/Javadoc product along with the hyperlinks to this website.
Description Subtemplates Deal with all sorts of text descriptions that originate from doc-comments in the Java code and elsewhere
text.tpl 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.
doc-reference.tpl Generates the hyperlinked text representation for Java language element references found in Java doc-comment tags like @see or {@link}.
block-tags.tpl Generates description sections typically produced from block-tags specified in doc-comments (of a Java program element).
summary.tpl Generates the summary description of a Java program element, which is used in summary tables.
doc-file-html.tpl Inserts in the documentation stand-alone HTML description files by framing them as other documentation pages and adding the navigation bar.

5. Possibility of unlimited customizations

Template Parameters

Since all the content and formatting of the generated JavaDoc is programmed entirely in the template set (which, in effect, becomes the actual doclet), what previously were command-line options provided by the Standard Doclet now simply become template parameters.

But introducing and checking parameters in templates is much easier than implementing some command-line options controlling a Java code. (In fact, it is writing a parameter description what takes the most time in many cases!) So, there can be a lot more template parameters than in the case of in traditional “command-line options” approach.

Parameter Inspector GUI

To control so many parameters, FlexDoc Doclet provides a GUI that includes the Parameter Inspector dialog (which is invoked from the main dialog on clicking “Params” button for the specified template).

On the following screenshot you can see the Parameter Inspector loaded with the parameters of FramedDoc.tpl:

The inspector content is constructed dynamically from the parameter definitions found in the given template.

Using Parameter Inspector, you can:

For further details, please see: Documentation | FlexDoc Doclet | Handling Template Parameters | Using Parameter Inspector GUI

Setting parameters from command line

Besides the Parameter Inspector dialog, you can always set any template parameters directly on the command line using -p option.

Please see: Documentation | FlexDoc Doclet | Handling Template Parameters | Setting parameters from command line

Specifying parameters via Standard Doclet options

JavadocClassic maps some of the Standard Doclet options to the default values of appropriate template parameters. This lets you using those options instead of specifying the corresponding parameters.

For more information about this capability and its implementation, see also:

Below is the list of all supported Standard Doclet options along with the template parameters, to which they are mapped:

Standard Option Mapped to Template Parameter
-author Include | Tags | @author
-bottom Generate | Bottom Text
-doctitle Documentation Title
-footer Generate | Navigation bar | Footer Text
-group Generate | Overview | Package Summary | Package Groups
-header Generate | Navigation bar | Header Text
-nodeprecated Include | Deprecated API
-nodeprecatedlist Generate | Cross-Reference Pages | Deprecated List
-nohelp Generate | Help
-noindex Generate | Cross-Reference Pages | Index
-nonavbar Generate | Navigation bar
-noqualifier Show | Package Qualifiers
Show | Package Qualifiers | Omit for Packages
-nosince Include | Tags | @since
-notree Generate | Cross-Reference Pages | Tree (Class Hierarchy)
-splitindex Generate | Cross-Reference Pages | Index | Split
-tag Include | Tags | Custom tags
-version Include | Tags | @version
-windowtitle Window Title

Generator options

Generator options control particular features of the selected output generator (that is what is hardcoded in Java code).

Generator options are separated from templates. They do not depend on the selected template as well as their settings are not used in templates at all. That's because templates are designed to be mostly independent of the particular output format. Only some general assumptions about the output format are accounted, for instance, whether it supports pagination and has page numbers.

Which particular generator options are available depends on the selected output format, which currently may be HTML, RTF and TXT (plain text). In the doclet GUI, after you have selected the destination output format, you can click «Options» button, which will invoke Format Option Inspector. Here you can see all options available for the given format and specify them. This screenshot shows the HTML Option Inspector:

Alternatively, you can specify any generator options (along with template parameters) through Javadoc command line using -o option.

Using custom CSS styles

You can apply also your own CSS styles to change how the generated documentation looks.

On the left you can see a documentation generated with the default formatting as specified in JavadocClassic templates. On the right, the same documentation generated with the application of a custom CSS stylesheet.
That stylesheet is provided along with the JavadocClassic templates as the file:
  • {JavadocClassic}/css/azure-theme_FramedDoc.css – for framed HTML
  • {JavadocClassic}/css/azure-theme_SingleDoc.css – for single-file HTML
How to specify it is shown in the HTML Option Inspector screenshot above. You should set:
  • Output | CSS | Generate named rules = all
  • Output | CSS | Generate named rules | Custom rules file = Stylesheet file path name

See Also: FlexDoc.XYZ | Documentation | Usage of CSS in generated HTML

Modifying templates with Template Designer

If template parameters and CSS styles are not enough, you can modify templates themselves using the Template Designer, which is a highly sophisticated GUI used to design/edit templates. It represents the template both in the form template components, which it is made of, and the output those components would generate.

This screenshot shows navbar.tpl template open in the Template Designer (click on the screenshot to see in full size). That template generates the navigation bar that appears in the framed HTML documentation.

The dialog over the designer pane represents template properties. The selected tab shows the list of formatting styles used in this template.

Note that all content and formatting you see in the generated output is programmed entirely in templates. In that respect, FlexDoc templates are not exactly “templates” in traditional sense (which typically serve to arrange how some output fragments readily provided by the generator are placed in the result output). Rather, FlexDoc templates are more akin to XSLT scripts. For more details, please read: FlexDoc.XYZ | Overview.

See Also: FlexDoc/Javadoc | Features | Actual Doclets as Template Sets

6. Getting Started

How to run JavadocClassic?

Running on Windows

  1. Download the FlexDoc/Javadoc archive from the downloads page.
  2. Unpack it in some directory, e.g.:

    C:\flexdoc-javadoc

    which we shall refer as '{flexdoc-javadoc}'.

  3. Edit:

    {flexdoc-javadoc}/bin/generator.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:
    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

  4. Run that generator.bat. You will see the Generator Dialog like shown on this screenshot:

  5. In the «Template» field, select
  6. In the «Output format» field, select HTML or RTF format.
    RTF will work only with SingleDoc.tpl template!
  7. Click «Run» button to start the generation.

    If you have no license installed, you will see this dialog:

    Just click OK to continue.

    This message notifies you, that everything will work in demo mode. It means that JavadocClassic will process all your Java classes files, however fully document only limited number of them. If the limit is not reached, you will get the complete documentation. Otherwise, some content will be omitted and the message included saying which limit exceeded.
    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 input data 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:

Running on Linux

  1. Unpack the downloaded FlexDoc/Javadoc archive at some location, which we shall designate as {flexdoc-javadoc}.
  2. Go to {flexdoc-javadoc}/bin/linux directory. Javadoc with FlexDoc Doclet is launched by generator.sh shell script file.

    Edit generator.sh to specify the JDK_HOME variable according to the location of JDK 11 (or later) installed on your system. Edit also the file "Permission" properties to allow it to be executed by Linux.

    Run that generator.sh. You will see the Generator Dialog.

  3. Anything else is the same as in case of Windows.

Running on macOS

For everything to work, you need to have JDK 11 (or later) installed on your Mac. You can download Java for Mac from either:
  1. Unpack the downloaded FlexDoc/Javadoc archive at some location (e.g. on Desktop), which we shall designate as {flexdoc-javadoc}.
  2. Go to {flexdoc-javadoc}/bin/macOS directory (open it with the Finder).

    Javadoc with FlexDoc Doclet is launched by generator.command shell script file.

    Because of security control, all macOS shell script files found in the downloaded FlexDoc/javadoc archive cannot be executed straight. However, that is easy to overcome as described below for generator.command file:
    1. First, open generator.command with TextEdit (confirm in the warning box that it is OK to open it). Then, simply resave that file via File | Save menu. With that procedure, you will sign generator.command as its “owner/creator”, which is a precondition to be able running it.
    2. On top of that, you will need also to assign generator.command with the executable privilege. Run the Terminal and type in it 'chmod u+x' followed by a space and the full pathname of the script file (instead of typing it, just drag generator.command from the Finder into the Terminal window). Then, press Enter.
    Now at last, you can run generator.command from the Finder just by clicking twice on it.
    When you run generator.command, the Generator Dialog should show up.
  3. Anything else is the same as in case of Windows.

Integration with Ant/Maven/Gradle

A demo about that you can find in your FlexDoc/Javadoc installation:
{flexdoc-javadoc}/integrations/ant/
{flexdoc-javadoc}/integrations/maven/
{flexdoc-javadoc}/integrations/gradle/
See Also:

7. Licensing

Demo Mode

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

Template Designer will work in demo mode as well. You will be able to run it, investigate some functionality, but unable to save any created/modified templates.

See Also: Licensing | Demo License

Trial License

The “FlexDoc/Javadoc” trial license (see below) unlocks full functionality of both JavadocClassic and Template Designer. You will be able to evaluate how everything works, generate the complete documentation by entire your Java project including all possible details (according to the settings specified in template parameters).

But there will be some limitations:

You can request trial license by clicking this button:

Then, you will be redirected to Try | Trial License page with “FlexDoc/Javadoc” preselected in the «Product» field.

The license file should be saved in FlexDoc/Javadoc 'lib' directory (near 'flexdoc-javadoc.jar' file):

{flexdoc-javadoc}/lib/

where '{flexdoc-javadoc}' denotes your FlexDoc/Javadoc installation directory.

See Also: Licensing | Trial License

Full License

The whole functionality described on this page is covered by the full “FlexDoc/Javadoc” license:

See Also: Licensing | Full License