FlexDoc/Javadoc - FlexDoc Doclet

Running Doclet
- Javadoc Command Line
- FlexDoc Doclet Options
Doclet GUI
Handling Template Parameters
Generation Phases
Error Reporting
- Finding Error Location in Template

“FlexDoc Doclet” is an encapsulation of FlexDoc/Javadoc Template Processor in the form of a Javadoc Doclet.

For more details, please see: FlexDoc/Javadoc | Features | Template Processor as Javadoc Doclet

1. Running Doclet

To run FlexDoc Doclet, basically you need to specify the doclet class using two Javadoc options:


  -docletpath
  <doclet_class_path>
  -doclet
  xyz.flexdoc.javadoc.Doclet

Javadoc Command Line

Here is the full command line to run Javadoc with FlexDoc Doclet:

javadoc [VM options] -doclet doclet_class -docletpath doclet_class_path [-sourcepath path] [--module-source-path path] [other_javadoc_options] [flexdoc_doclet_options] [sourcefilenames] [packagenames] [-subpackages pkg1:pkg2:...] [--module module1,module2,...]

All arguments are explained in this table:

Command/Arg	Explanation
`javadoc`	A system command that starts Javadoc. On Windows, that command may look like the following: `"C:\Program Files\Java\jdk-17\bin\javadoc"` (Just do not forget to enclose it in double quotes, when the pathname contains spaces!)
`[VM options]`	The options passed to JVM that runs Javadoc. When you generate documentation for a big project, it is important to ensure that JVM will allocate enough memory for the heap (otherwise, the generator will slow down and may run out of memory). The maximum heap size should be specified here using -J-Xmx option. For example, setting -J-Xmx2048m will allocate 2 Gb for the heap. The Template Processor / output generator may need a lot of memory as it stores large quantity of temporary data in hash-tables in order to boost performance. According to our tests, 2-4 Gb heap would be enough for a project containing several thousand Java classes.
`-doclet doclet_class`	The Javadoc `-doclet` option to specify the fully-qualified name of the doclet starting class. For FlexDoc Doclet, it should be the following: `-doclet xyz.flexdoc.javadoc.Doclet`
`-docletpath doclet_class_path`	The Javadoc `-docletpath` option to specify the path to the doclet starting class file. This must be the pathname of the FlexDoc/Javadoc Java library file. On Windows, everything should look like as follows: `-docletpath "%FDH%\lib\flexdoc-javadoc.jar"` where `'%FDH%'` must expand to the pathname of FlexDoc/Javadoc home directory (e.g. `C:\flexdoc-javadoc`) The precise form of the file pathname depends on the OS. (For instance, on Linux the name-separator is '/') When the file pathname contains spaces, it should be enclosed in double quotes! (Otherwise, it will be treated as separate arguments.)
`[-sourcepath path]`	Specifies where to find Java source files. This option should be used only in case of non-modular or single-module Java project. Basically, it should point to a file system folder (or folders) containing the entire Java package tree to document. In the case of single-module project, that folder may also contain the `module-info.java` file defining that module. No other `module-info.java` files must be found on the source path specified with this option. More details about this option can be found at: https://docs.oracle.com/en/java/javase/17/docs/specs/man/javac.html#option-source-path
`[--module-source-path path]`	This option should be used in case of multi-module Java project. It should point to a file system folder (or folders) containing all the module folders to document. Each module folder must be named after the module and contain the corresponding `module-info.java` file along with the all package tree that belong to that module. More details about this option can be found at: https://docs.oracle.com/en/java/javase/17/docs/specs/man/javac.html#option-module-source-path
`[other_javadoc_options]`	Any other Javadoc core options, some of which are the same as Java compiler options. For details, please see: https://docs.oracle.com/en/java/javase/17/docs/specs/man/javadoc.html https://docs.oracle.com/en/java/javase/17/docs/specs/man/javac.html
`[flexdoc_doclet_options]`	The options processed by the FlexDoc Doclet (see below)
`[sourcefilenames]`	Specify the space-separated list of Java source files (*.java) to document. These must be the full file pathnames.
`[packagenames]`	Specify the space-separated list of Java packages to document. These must be the fully qualified package names.
`[-subpackages pkg1:pkg2:...]`	Specify the list of Java packages to document along with all their subpackages recursively. For details, please see the `-subpackages` option of Javadoc.
`[--module module1,module2,...]`	Specify the list of Java modules to document. For details, please see the `--module` option of Javadoc.

FlexDoc Doclet Options

Here are all command line options specifically processed by FlexDoc Doclet:

-config
-d
-flexdocconfig
-errlog
-f

-format
-launchviewer
-license
-link
-linkoffline

-nodialog
-o
-overview
-p

-taglet
-tagletpath
-template

The number of options is relatively small for two reasons:

Since all informative content of the generated documentation is programmed entirely within templates, it is the matter of template parameters to control this. The templates parameters are passed via the -p option.
The output formats do have their specific options. But since such options are different for each particular output format and the number of supported formats will grow, all output format options are specified in the uniform way via -o option (the same as the template parameters).

Effectively, the number of various generator settings may be so great that the FlexDoc Doclet provides a different and more convenient way for specifying all of them – the Doclet GUI.

Here are the option details grouped by category:

Template Options

-template <file>

Specifies the main template file to be executed by the generator. All documentation generation is controlled by this template. The main template may call from itself another templates (subtemplates) producing either a single output file or multiple files (framed documentation).

-p <parameter_name>=<value>

Specifies the value of a template parameter.

Notes:

The necessary parameter names can be found in the Template Parameter Inspector invoked from the Generator Dialog:
The parameter name and value (separated with '=') together must form a single command-line argument.
That is necessary to reconciles everything with systems like Ant, which allow specifying only command-line options with a single argument.
If the parameter value contains spaces, the entire parameter name/value specification must be enclosed it in double quotes. For example:
-p "title=My Docs"
The boolean values should be specified as "true" and "false" strings. For example:
-p include.deprecated=true
There are also enum parameters, which are strings limited to only fixed number of values. You can find all possible values accepted by an enum parameter in the Parameter Inspector as well.
Multi-valued (list) parameters can be equally specified on the command line using this option. See Specifying list parameter on command line for more details.

Output Options

-format <HTML | RTF | TXT>

Specifies the output format. By default, HTML.

-o <option_name>=<value>

Specifies the output format option.

Notes:

You can find the necessary option names in the Format Option Inspector invoked from the Generator Dialog. Basically, it is the same as in case of -p option.
The values of the boolean options should be specified as "true" and "false" strings. For example: -o rtf.storeGraphicsInRTF=false

-d <directory>

Specifies the destination directory for the generated documentation. By default, this is the current directory (the one designated by "." pathname). This option works in conjunction with the -f option.

The documentation files are distributed in the following way:

In the case of a single-file documentation
1. The output document is placed in the destination directory under default file name 'templatename.formatextention' (for example, in the RTF output format, template SingleDoc.tpl will produce document 'SingleDoc.rtf'). The -f option may override this name.
2. All associated files (such as images, if not included in the document) are placed in the 'docname_files' subdirectory near the main document.
In the case of a framed multiple-file documentation
1. By default, all generated files and subdirectories are placed in the specified destination directory. The frameset file produced by the main template is saved under the name 'index.html'. This is the same as the output produced by the Standard Javadoc doclet.
2. If a different name 'docname' is specified with the -f option, the frameset file is saved under this name. All other files and the subdirectory tree are moved into 'docname_files' subdirectory near the frameset file.
  This makes the whole documentation to look as to consist of only two file entities, which may be easier to distribute yet during the generation, especially when different types of documentation are produced from the same Java sources (e.g. by different templates or with the different parameters).

Examples:

-template SingleDoc.tpl -format RTF -d c:\out: generate the document file c:\out\SingleDoc.rtf with the associated files subdirectory c:\out\SingleDoc_files\ (if any)
-template SingleDoc.tpl -format HTML -d c:\out -f OpenAPI: generate the document file c:\out\OpenAPI.html with the associated files subdirectory c:\out\OpenAPI_files\ (if any)
-template FramedDoc.tpl -format HTML -d c:\out: generate the framed documentation located in the directory c:\out\ with the main file index.html
-template FramedDoc.tpl -format HTML -d c:\out -f OpenAPI: generate the framed documentation with the main file c:\out\OpenAPI.html and all other files located in the directory c:\out\OpenAPI_files\

-f <file>

Specifies the documentation output file name. This option works in conjunction with the -d option and specifies the name of the main output file (the one associated with the main template).

Typically, it should be used to specify a pure name associated with the generated documentation (for example, 'DocletAPI'). However, the pathname may also be used. In that case, it is interpreted against the initial destination directory (specified with the -d option) and may override it. If the pathname is the absolute one, the -d option is effectively ignored.

-launchviewer <true | false>

Tells the generator to execute a specific non-Java command to launch an external application able to view the generated result (for instance, an Internet browser to view HTML documentation).

Precisely, this command is specified in flexdoc.config file found near flexdoc-javadoc.jar file in the lib directory.

Examples:

-launchviewer true: Do launch viewer

-launchviewer false: Do not launch viewer, no matter what's specified in the generator.config

Configuration Options

-config <file>

Specifies the generator config file, which may contain options written manually or using the Generator Dialog. All options not provided directly on the command line are looked for in this file.

The Generator Dialog also uses this file to store all options and parameters specified interactively. If the config file does not exist, the Generator Dialog will try to create it by the provided pathname.

By default, the location of the generator configuration file is specified in the flexdoc.config (located in lib directory). If no other config file is provided, it is automatically loaded from that location (if found).

-flexdocconfig <file>

Specifies an alternative path to the FlexDoc main configuration file. By default, this file is 'flexdoc.config' which is searched in the directory where the FlexDoc Java library file 'flexdoc-javadoc.jar' is located. If not found, flexdoc.config is created automatically with default settings.

-license <file>

Specifies the location of the license file.

You may need this option when the way how the license file is searched/loaded by default does not fit to you. See also: Documentation | Configuration Files | flexdoc.license

The license directly specified with this option on the command line will override any other licenses (e.g. assigned in flexdoc.config or found near flexdoc-javadoc.jar).

Other Options

-link <extdocURL>

Creates links to existing javadoc-generated documentation of external referenced classes.

This option works the same as the -link option supported by the Standard Doclet.

The exact processing of both -link and -linkoffline options is programmed within templates using a Javadoc-specific FlexQuery function: getExternalDocURL(). When FlexDoc Doclet finds either -link or -linkoffline option on the Javadoc command line, it processes such an option so that the content of the element-list/package-list file referred from it is loaded into a special internal hash-table. Further, getExternalDocURL() function uses that table to translate any Java qualified name into a possible URL of the external documentation.

-linkoffline <extdocURL> <packagelistLoc>

This option is a variation of -link; they both create links to javadoc-generated documentation for external referenced classes. Use the -linkoffline option when linking to a document on the web when the Javadoc tool itself is "offline" – that is, it cannot access the document through a web connection.

This option will work the same as the -linkoffline option provided by the Standard Doclet. See also -link option for more details about how it is implemented.

-nodialog <true | false | quiet>

Do not invoke the Doclet GUI.

Parameters:

true

if this (or no parameter) is specified, the FlexDoc Doclet starts the generation immediately according to the setting specified on the Javadoc command line and loaded from the generator config (see -config option). Then, the doclet exits.

false

this is the same as when the -nodialog option was not specified at all. The Generator Dialog will be invoked.

quiet

start the generation immediately (without dialog) and suppress displaying most of the generator messages to screen (see also -quiet option). The generation progress counter will be printed.

-errlog <file>

Specifies the error log file used when the FlexDoc Doclet is executed without the Generator Dialog (i.e. when -nodialog option is also specified on the command line).

By default, when an unexpected error/exception occurs during the generation and no GUI is enabled, all details about the error are printed to the standard console.

Using this option, you can assign a separate error log file, into which the detailed ERROR REPORT is dumped each time an error happens. Only brief messages will get on the console in that case.

The error log file should be specified as an absolute or relative file pathname. When the pathname points to a directory, it will be extended with the default “FlexDocXYZ.log” name (for example, setting "-errlog ." will be interpreted as 'FlexDocXYZ.log' file located in the current directory).

If the error log file does not exist, it is created in the event of error. Otherwise, the ERROR REPORT is appended to the existing file. In the case of any I/O error related to the error log file itself, everything will be printed to the console (along with additional the log file error message).

-overview <file>

Specifies the pathname of an HTML file with the text to be placed in the overview documentation on the Overview page/section (e.g. overview-summary.html).

This option works the same as the -overview option supported by the Standard Doclet.

Since the new Doclet API (introduced with Java 9), the -overview option is no longer among the core options of Javadoc. So, it must be supported by a doclet, which FlexDoc Doclet does using the functionality of the Doclet API and other related to it.

The HTML file specified with the -overview option may include:

Any HTML markup
The references to image files (specified with <img> tags). If an image file is specified relatively to the overview file (specified with this option), that image will be copied in the result documentation.
Javadoc inline-tags and block-tags allowed for the overview.

-taglet class

-tagletpath tagletpathlist

Specify the taglet class and the search paths for taglet class files.

These options work the same as the -taglet and -tagletpath options supported by the Standard Doclet. See also Taglet interface documentation.

When FlexDoc Doclet finds a -taglet option on the Javadoc command line, it loads the doclet class, initializes the doclet and puts it in a special internal hash-table (according to tag name supported by the taglet). The exact application of taglets is programmed in templates using a Javadoc-specific FlexQuery functions:

getTaglets()
getTaglet()
callTaglet()

In case of JavadocClassic template set, it is found in text.tpl and block-tags.tpl.

2. Doclet GUI

Besides the command line options, FlexDoc Doclet provides a different more user-friendly way to specify most of the settings used by the generator.

If no -nodialog option specified on the Javadoc command line, when the FlexDoc Doclet starts, it invokes the following dialog:

Generator Dialog

The dialog fields are initialized with the option values specified on the command line or loaded from the generator config file (see also -config option).

Specifying Template

In the «Template» field, you should specify the pathname of the main template to be interpreted by the generator. The combo-box list contains the last used templates which allows you quickly to pick one as soon as you need.

This field duplicate -template option specified on the generator command line.

Setting Template Parameters

For the specified template, the «Params» button invokes the Parameter Inspector dialog, like the one shown on this screenshot:

The inspector contents is constructed dynamically from the parameter definitions obtained from the given template (the one specified in the «Template» field in the Generator Dialog). The parameter values are displayed and edited according to their types.

The bottom panel displays the description of the selected parameter (which is also obtained from the template). The first line of the description (the white text) shows the internal parameter name. Use this name in the -p option to specify the parameter value on the Javadoc command line.

Selecting Output Format

The «Output format» combo-box allows you to select the output format of the generated documentation. Currently, the following formats are supported:

HTML
RTF
TXT

Since all document templates are format independent, if you have specified such a template in the «Template» field you can freely use any output format with it. The frameset templates are supported only by HTML output format.

Similar to the template parameters, the «Options» button near the «Output format» combo-box invokes the Format Option Inspector which is specific for the selected output format.

The bottom panel in the inspector dialog displays the description of the selected option. The first line of the description (the highlighted text) shows the internal option name. This name should be used in the -o option to specify the format option value on the generator command line.

The following screenshots show the option inspectors for each supported output format:

HTML Option Inspector

RTF Option Inspector

TXT Option Inspector

Specifying Output Location

Output folder: Use this field to specify the destination directory for the generated documentation. See -d option for more details.
Output file: Use this field to specify the documentation main output file name. See -f option for more details.

Starting Generation

Once all settings prepared, the generator can be started by clicking the «Run» button. Then, the dialog transforms and the progress panel appears:

Generating documentation

The progress bar tracks the generation progress and shows the name of the output file being currently generated. The “Cancel” button can stop the generation at any moment.

Once the generation has finished or cancelled, the Generator Dialog transforms itself back to the initial state. Then, the new settings can be entered and the generation started again. At that, the Java sources information provided by Javadoc via Doclet API remains the same (as Javadoc doesn't care what exactly a particular doclet is doing with it). This allows you during the same session to generate different kinds of documentation by different templates, in different output formats and so on.

When the generation was successful and the «Launch Viewer» check-box selected, the generator will try to launch an external application (e.g. MS Word) to view the produced result. See -launchviewer option for more details about this setting.

3. Handling Template Parameters

Since all the content and formatting of the generated JavaDoc is programmed now 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.

Using 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 JavadocClassic | FramedDoc.tpl (click to view an expanded form):

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

Using Parameter Inspector, you can:

Edit each parameter according to its type.
View the parameter HTML description (it is also obtained from the template) as well as the parameter internal name (the first line) and possible values, which must be specified in -p option, when you set that parameter on the command line (see below).

Once you have changed some parameters and closed the inspector dialog (with «OK» button), the new values will be stored (along with the parameter names) in the generator.config file. Further, the generator will use the parameter values found in that file. The same will happen when you open the Parameter Inspector dialog next time. The template parameters, whose names match those found in the generator.config file, will be initialized with the corresponding values from that file.

The parameters are organized in groups (which may contain subgroups and so on). A group heading may also be a parameter itself.

Each parameter group may appear in expanded or collapsed state like a tree node. The group states are also saved in the generator.config file to be restored again when the inspector is invoked next time for the same templates. Using inspector popup menu, you can quickly reset all parameters in a group to their default values.

The check-boxes in «Default» column indicate whether the default values of the corresponding parameters are used.

The default value of a parameter is specified in the parameter definition in the template. Alternatively, the default value may be calculated dynamically from the values of other parameters or settings by a special FlexQuery-expression also specified in the parameter definition.

The same parameters in different main templates may have different default values.

When a parameter is specified in the Parameter Inspector, its value is saved in the generator.config file. If the parameter value is NOT found in that file, the default value will be used (or calculated).

Setting parameters from command line

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

The -p option requires the parameter internal name, which you can find in the bottom panel of the Parameter Inspector dialog (when the necessary parameter is selected). For example:

internal name of a template parameter

In this case, the -p option would look like the following:

-p gen.refs.index=true

The parameter values specified with -p options on the Javadoc command line will override the values of those parameters found in the generator.config.

Using Doclet GUI to prepare parameters for command line

A possibility to specify template parameters on the command line may be particularly important when you prepare an Ant or Maven build file. But that seems like your will have to fill your build file with lots of -p options for all those numerous parameters. Right? Actually, not!

Rather than specifying all the template parameters (and other generator settings) directly with command line options, you can use Doclet GUI to prepare a special generator.config file and, then, provide only that file with -config option.

Here is how it works, step by step:

Run FlexDoc Doclet like follows:
javadoc ... -doclet xyz.flexdoc.javadoc.Doclet -nodialog false -config C:\project\...\myconfig.config ...
That should start the Doclet GUI.
Edit with the GUI all the settings you need (including all template parameters) and click “OK” button in each dialog where you have changed anything. That will cause all new settings to be saved in your specified config file.
Now, you can use that config file (with all the prepared settings) anywhere you wish (including in any Ant/Maven build file) just by specifying the only option:
-config C:\project\...\myconfig.config
Above this, you can still use any other options (like -p and -o) to override selectively the corresponding settings stored in the myconfig.config.

Setting template parameters via Standard Doclet options

Since the version 1.6.0, FlexDoc/Javadoc supports a possibility to use many of Standard Doclet Options along with (or instead of) the template parameters.

Such options like -author or -splitindex can be mapped to the default values of the corresponding template parameters. So, by using them you actually specify again some template parameter, implicitly now. However, it means that whether and which Standard Doclet options are supported depends on a particular template set.

Currently, that functionality is supported only by “JavadocClassic” template set. Here you can see which Standard Doclet options can be used with it and on which template parameters they are mapped:

FlexDoc/Javadoc | JavadocClassic | Template Parameters | Specifying parameters via Standard Doclet options

Multi-valued (list) parameters

Since the version 1.5.6, FlexDoc/Javadoc supports multi-valued template parameters (which we shall call also list parameters, for short).

List parameters allow you to pass into template the whole vector of different values associated with the same parameter name. This provides a universal mechanism for implementing a user control over how a set of templates processes a certain type of data (or situations) that may come in unlimited number of variations.

Before this, such functionality was actually emulated with a string parameter, whose value was expected to contain separate items delimited with a special character (e.g. semicolon). That representation was parsed in a template so as to produce from it an array of values that could be used in further processing. For example, so was implemented (before v1.5.6) the processing of filter.byTags.exclude.classes and show.qualifier.omit parameters of the basic template set.

Now, the parameter inspector also represents the whole value of a list parameter as a concatenation of all value items (represented as strings) delimited with a separator character. However, there is no need any longer to process that string representation within a template. Rather, it will be parsed automatically by the Template Processor (as well as the parameter inspector ensures its integrity).

Specifying list value in Parameter Inspector

In Parameter Inspector dialog, the entire list parameter value is displayed as a single string in the value field of the inspector row, where you can edit it as well:

editing a list parameter inside the inspector row

Additionally, the list value can be edited as a multi-line text in a special dialog (invoked by the ellipsis button):

editing a list parameter in a separate dialog

At that, when the allowed value item separators include newline, all currently used separators will be replaced with it so as to show each value item on a different line. When the editing in this dialog is finished, all newline-separators will be automatically replaced with another available separator suitable for single-line representation.

You can see all available value item separator characters in the “Parameter Description” window, when the list parameter is selected:

parameter properties and description

The separators are specified in the template along with the parameter definition.

Using escapes

When the characters recognized as value item separators may also appear within the value items themselves, the list parameter may be defined so as to recognize escapes. In that case, each separator character can be equally used within value items if escaped with a backslash. For example, given that ';' is a separator, the following value item:

my;odd;tag

can be specified like this:

my\;odd\;tag

If a backslash is not consumed by an escape it will be remained in the text as is. To make sure that a backslash is not part of some escape, you may add another backslash. A sequence of two backslashes ("\\") is an escape itself, which represents a single backslash. This is important because backslashes may be used also in a secondary system of escapes within value items, which is specific to the given parameter.

When the escapes are recognized, the sequence "\n" is reserved to encode a newline character. The encoding of newline may be needed, for instance, when it is used not as a value item separator, but rather within multi-line content of value items themselves. In that case, the "\n" escape allows flattening the entire list value into a single line. This may be particularly important for specifying the list parameter on the command line (see also below).

Some list parameters can be specified to ignore escapes. This may be needed when backslashes must be frequently used within value items. (For example, the parameter will accept a list of Windows file pathnames.)

All possible escapes related to specifying of the value of a list parameter as a whole can be found in the «Parameter Description» window.

As an example of extensive usage of escapes, see description of include.tag.custom parameter of the basic template set.

Specifying list parameter on command line

To specify a list parameter on Javadoc command-line you should encode the entire list value into a single string (using the value item separators and possibly escapes) and provide that string as a -p option argument.

For example, suppose you need to pass into a template the list parameter include.tag.custom with three value items:


prjtype:a:Project Type:

todo:cmf:To Do:

priority:cmf:Priority

You can do this using a single command line option (given that ';' is a value item separator):


-p "include.tag.custom=prjtype:a:Project Type:;todo:cmf:To Do:;priority:cmf:Priority"

The quotes are needed here because the full parameter value contains spaces and must be treated as a single command-line argument.

Alternatively, you can pass the same list value using multiple -p options, each one for a separate value item. e.g.:


-p "include.tag.custom=prjtype:a:Project Type:"
-p "include.tag.custom=todo:cmf:To Do:"
-p include.tag.custom=priority:cmf:Priority

You can even combine the two approaches simultaneously:


-p "include.tag.custom=prjtype:a:Project Type:;todo:cmf:To Do:" 
-p include.tag.custom=priority:cmf:Priority

Multiple options specifying the same list parameter can be mixed with other options on command line. However, the order in which the parameter options follow is important, because it defines the ordering of the list value items received by the template.

4. Generation phases

FlexDoc generates the whole documentation in two phases: estimation phase and generation phase.

In the estimation phase, the generator quickly passes over all the source data and partially interprets the involved templates. During that, it collects the names and location of all documentation files to be created and all possible hypertarget locations within them. It also makes an estimation of the total generation time in order to graduate the progress.

During the estimation phase, only the message "Scanning data source, please wait..." is displayed on the generator dialog's progress bar (or printed on console). Please note, the estimation phase may take some time! On a huge project (plus a slow computer), it may last several minutes. This does not mean, the generator hangs. Please wait!

During the generation phase, all template components are being fully interpreted and the real output generated. The progress bar is alive and shows what's being generated at the particular moment. Without Doclet GUI, an estimated percent of the finished output will be periodically printed.

5. Error reporting

Both FlexDoc Doclet and Template Designer may encounter various unexpected error situations. During the generation, the unexpected errors and exceptions may arise because of the following reasons:

I/O errors (e.g. invalid file pathnames, disk full, etc.)
Template errors/bugs (when something is wrongly specified in templates).
Data source exceptions (in the case of FlexDoc/Javadoc, these exceptions may come from the Doclet API).
FlexDoc core exceptions (may be caused by bugs not discovered and fixed yet).

FlexDoc tries to catch all such errors/exceptions and report about them along with the full diagnostics possible (i.e. where exactly and how the error has happened).

When the Generator Dialog is enabled, any error is reported via the error message dialog, like the one shown on the screenshot:

Error Message Dialog

The error dialog shows brief information about the error. When more details are available, a full ERROR REPORT is created and dumped to the system clipboard. You can easily extract it (e.g. under MS Windows, just run Notepad and press Ctrl+V).

When the generator is executed without the GUI (-nodialog option is specified on the generator command line), by default, all exception/error details will be sent to the standard console. However, using -errlog option, you can specify a separate error log file. In that case, the ERROR REPORT will be dumped in that file; only brief messages will get on the console.

The detailed ERROR REPORT includes:

The general info about JVM, OS, command-line arguments, etc.
All available error messages.
Template Location Trace that shows precisely which templates/components/properties (i.e. template locations) were being interpreted when the error happened.
Each template location is identified both verbally and, when applicable, with the line number in the template file, where the given component/property is defined. Additionally, for some template locations, the context element is reported that shows which XML element (along with its XML file) was being processed by the given template/component/property at the moment of the error.
Having a line number in the template file, you can easily find the error location direct in the Template Designer.
Java Exception Stack Trace (when the error was caused by some unexpected Java exception).

Here is how an ERROR REPORT looks (the template line numbers and context elements are highlighted with special colors):

================================================================================
FLEXDOC.XYZ ERROR REPORT, 2023-03-31 07:59:40
================================================================================
FlexDoc/Javadoc, Version 2.0
Main class: xyz.flexdoc.javadoc.Doclet
Arguments: -overview overview.html ...
java.version=17
java.vendor=Oracle Corporation
sun.arch.data.model=64
os.name=Windows 10
os.arch=amd64
os.version=10.0
locale=en_US
--------------------------------------------------------------------------------
GENERATOR INFO
--------------------------------------------------------------------------------
Template Application: JavadocClassic, Version 3.0
Main Template: C:\flexdoc-javadoc\templates\classic\FramedDoc.tpl
Output Format: HTML
Output Folder: C:\flexdoc-javadoc\out\
--------------------------------------------------------------------------------
ERROR DETAIL
--------------------------------------------------------------------------------
Generator Exception:
No element map found with id 'all-known-implementing-classes'
--------------------------------------------------------------------------------
When executing function call 'findElementsByKey' (expr: Ln 1, Col 1)
--------------------------------------------------------------------------------
at Expression for Element Enumeration (class.tpl:1316)
at Element Iterator by 'Class' (class.tpl:1312)
at Folder Section (class.tpl:1257)
at Template: C:\flexdoc-javadoc\templates\classic\lib\class\class.tpl
   with context element: Class {java.io.Closeable}
at Call Template 'lib\class.tpl' (FramedDoc.tpl:1479)
at Element Iterator by 'Class' (FramedDoc.tpl:1463)
at Element Iterator by 'Package' (FramedDoc.tpl:1403)
at Template: C:\flexdoc-javadoc\templates\classic\FramedDoc.tpl
   with context element: DocletEnvironment

Finding Error Location in Template

FlexDoc/Javadoc templates are plain text files, where every component/property definition starts from a new line. So, having a line number in the template file, you can open it in some text editor and find the necessary line. However, that won't be very useful because templates are not supposed for manual editing.

Instead, using the same line number information, you can quickly find the error location directly in the Template Designer:

Open the template in the Template Designer.
In the main menu select: Edit | Find. You will see a dialog where in «Search for» combo-box should be: Line number in template file
In the «Line Number» field enter the line number (that you took from the ERROR REPORT) and click «Search».
Now, in the «Search Results» pane you should see a tree of some template components. The last node of that tree depicts the component/property that was searched for (corresponding the entered line number). All nodes above are its ancestors (that is all those components that contain the found one). You can walk that tree by clicking with mouse on particular nodes.
When you click «Show Location» button, the Template Designer (behind the dialog) will adjust itself to show the component currently selected in the «Search Results» tree (or when it's a property, then the component containing it). That component will be selected in the designer pane as well. Now you can close the search dialog and edit the selected component or see its properties.
The selected component is highlighted in the designer pane (on the right) with a faint blue box around it. When it is a template section, it is also highlighted in the section tree (on the left).

Below is the compound screenshot of the whole search process described above (click to see in full size):

See Also: