# DocFlex/Javadoc - Documentation - DocFlex Doclet

1. Running Doclet
   - Command Line Options
     - Template Options
     - Output Options
     - Configuration Options
     - Other Options
2. Doclet GUI
   - Specifying Template
     - Setting Template Parameters
   - Selecting Output Format
     - HTML Option Inspector
     - RTF Option Inspector
     - TXT Option Inspector
   - Specifying Output Location
   - Starting Generation
3. Handling Template Parameters
   - Using Parameter Insector GUI
   - Setting parameters from command line
   - Using Doclet GUI to prepare parameters for command line
   - Setting template parameters via Standard Doclet options
   - Multi-valued (list) parameters
     - Specifying list value in Parameter Inspector
     - Using escapes
     - Specifying list parameter on command line
4. Generation Phases
5. Error Reporting

## 1. Running Doclet

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

> `-docletpath <doclet_class_path> -doclet com.docflex.javadoc.Doclet`

If you are not sure what that means, here is the full Javadoc command line:

> `javadoc` | `` | `[VM options] -docletpath <doclet_class_path> -doclet <doclet_class> [options] [packagenames] [sourcefilenames] [-subpackages pkg1:pkg2:...]`

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\jdk1.6\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-Xmx256m will allocate 256 Mb for the heap.
DocFlex generator may need a lot of memory as it stores lots of temporary data in hash-tables in order to boost performance. However, according to our tests, 256 Mb heap appeared to be quite enough to generate an RTF documentation for a project with something close to 1000 Java classes. That was on 32-bit Java. For 64-bit Java (running on 64-bit OS), we recommend to double the amount of allocated memory since lots of internal things (like memory pointers) get doubled in size on 64-bit (as compared to 32-bit OS). So, on Windows 7 64-bit you should specify `-Xmx512m`, instead of `-Xmx256m`.
`-docletpath` | The Javadoc `-docletpath` option to specify the path to the doclet starting class file.
`<doclet_class_path>` | This must be the pathname of the DocFlex/Javadoc Java library file. On Windows platform, it should look like the following: `"%DFH%\lib\docflex-javadoc.jar"` or `"%DFH%\lib\docflex-doclet.jar"` where `'%DFH%'` must expand to the pathname of DocFlex/Javadoc home directory (e.g. `C:\docflex-javadoc`) `docflex-javadoc.jar` is the Java library in Full Edition `docflex-doclet.jar` is the Java library in DocFlex/Doclet edition Notes: 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.)
`-doclet` | The Javadoc `-doclet` option to specify the fully-qualified name of the doclet starting class.
`<doclet_class>` | The qualified name of the DocFlex Doclet starting class: `com.docflex.javadoc.Doclet` (the same for all editions)
`[options]` | All other Javadoc options. This includes both the Javadoc core options and the options processed by the DocFlex Doclet (see below).
`[packagenames] [sourcefilenames] [-subpackages pkg1:pkg2:...]` | Specify the Java packages and classes to document. For further explanations, please see Javadoc Reference Guide, e.g. by this link: http://docs.oracle.com/javase/6/docs/technotes/tools/windows/javadoc.html#referenceguide

### Command Line Options

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

| -config -d -docflexconfig -errlog -f |
| -format -launchviewer -license -link -linkoffline |
| -nodialog -O -P -quiet -template

The number of options is relatively small for two reasons:

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

2. 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 DocFlex 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> <value>

or

-p:<parameter> <value>
  Specifies the value of a template parameter.
  Notes:
  - You can find the necessary parameter names in the Template Parameter Inspector invoked from the Generator Dialog.
  - 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 see all possible values accepted by an enum parameter in Parameter Inspector.
  - Now DocFlex supports multivalued (list) parameters, which can be equally specified on the command line using this option. See Specifying List Parameter on Command Line for more details.
  - When the parameter value contains spaces, enclose it in double quotes (for example: `-p:title "My Docs"`).
  - Formerly, this option had the following format (which is also recognized now):

    -P<parameter>=<value> or -p:<parameter>=<value>

    The format was changed in order to have the <value> passed as a separate command-line argument. This is needed for compatibility with Apache Ant (particularly, in some situations when the value string contains spaces).

#### Output Options

-format <HTML | RTF | TXT>
  Specifies the output format. By default, HTML.
-O<option> <value>

or

-o:<option> <value>
  Specifies the output format option.
  Notes:
  - You can find the necessary option names in the Format Option Inspector invoked from the Generator Dialog.
  - The values of the boolean options should be specified as `"true"` and `"false"` strings (for example: `-o:rtf.storeGraphicsInRTF false`).
  - Formerly, this option had the following format (which is also recognized now):

    -O<option>=<value> or -o:<option>=<value>

    The format was changed in order to have the <value> passed as a separate command-line argument. This is needed for compatibility with Apache Ant (particularly, in some situations when the value string contains spaces).
-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 PlainDoc.tpl will produce document 'PlainDoc.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 PlainDoc.tpl -format RTF -d c:\out`
      generate the document file `c:\out\PlainDoc.rtf` with the associated files subdirectory `c:\out\PlainDoc_files\` (if any)
    `-template PlainDoc.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 docflex.config file found near `docflex-javadoc.jar` (or `docflex-doclet.jar`) file in the `lib` directory.

  Examples:
    `-launchviewer`
      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 docflex.config (located in `lib` directory). If no other config file is provided, it is automatically loaded from that location (if found).

  See also: Handling Template Parameters | Using Doclet GUI to prepare parameters for command line

-docflexconfig <file>
  Specifies an alternative path to the DocFlex main configuration file. By default, this file is `'docflex.config'` which is searched in the directory where the DocFlex Java library file `'docflex-javadoc.jar'` (or `docflex-doclet.jar`) is located. If not found, docflex.config is created automatically with default settings.
-license <file>
  Specifies the location of the license file.

  You may need this option when you use the full edition of DocFlex/Javadoc and your license allows you to execute your templates only in its presence. At that, the way how the license is searched by default does not fit to you (see Documentation | Configuration Files | docflex.license).

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

#### Other Options

-link <extdocURL>
  Creates links to existing javadoc-generated documentation of external referenced classes.

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

  Precisely, the processing of both -link and -linkoffline options is programmed within the templates using a Javadoc-specific FlexQuery function: `getExternalDocURL()`. When DocFlex/Doclet meets either -link or -linkoffline option on the Javadoc command line, it processes such an option so that the content of the `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 DocFlex 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 DocFlex 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. (See also Error Reporting for more details.)

  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 “docflex_error.log” name (for example, setting `"-errlog ."` will be interpreted as `'docflex_error.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).

-quiet[=<true | false>]
  Suppress displaying most of the generator messages to screen.

  Note: Since Java 5, this option is used by Javadoc itself as one of its core options. If you want to suppress only DocFlex Doclet messages but still see the generation progress counter, use `-nodialog=quiet` option instead.

## 2. Doclet GUI

Besides the command line options, DocFlex 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 DocFlex Doclet starts, it invokes the following 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.

See also: Handling Template Parameters.

### 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:

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.

See also: Generation Phases

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

For instance, “JavadocPro” template set currently supports more than 70 parameters.

### Using Parameter Insector GUI

To control so many parameters, DocFlex 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 JavadocPro | 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:

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:

1. Run DocFlex Doclet like follows:

   `javadoc ... -doclet com.docflex.javadoc.Doclet -nodialog=false -config C:\project\...\myconfig.config ...`

   That should start the Doclet GUI.

2. 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.
3. 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`

4. 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, DocFlex/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 “JavadocPro” template set. Here you can see which Standard Doclet options can be used with it and on which template parameters they are mapped:

DocFlex/Javadoc | JavadocPro | Template Set Overview | Specifying parameters via Standard Doclet options

The primary reason why we needed to process Standard Doclet options was because the recent versions of Maven always emit some of those options no matter is there a custom doclet or not. Although the Javadoc itself does not mandate for a custom doclet to process any Standard Doclet options, without doing something about them, DocFlex Doclet would simply fail now under Maven (because Javadoc requires for any non-core option to be recognized by the doclet). To deal with that problem, since v1.6.0, DocFlex Doclet includes a list of all possible Standard Doclet options (along with their parameter numbers) so as to tell Javadoc that any of such options has been recognized (in case it was fed to the doclet). As a by-product of this, it became possible to read those options within templates and initialize from them the corresponding template parameters.

### Multi-valued (list) parameters

Since the version 1.5.6, DocFlex/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 exclude.byTags.classes and omit.packageQualifiers.for 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 Generator (as well as the parameter inspector ensures its integrity).

#### Specifying list value in Parameter Inspector

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

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

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:

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

DocFlex 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 the DocFlex Generator and the Template Designer may encounter various unexpected error situations. During the generation, the unexpected errors and exceptions may arise because of the following reasons:

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

DocFlex 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:

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

The detailed ERROR REPORT includes:

- The general info about JVM, OS, command-line arguments, etc.
- All available error messages.
- The Template Location Trace that shows which precisely template component was being interpreted when the error happened.
- The Java Exception Stack Trace (when the error was caused by some unexpected Java exception).

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

Copyright© 2003-2012 Filigris Works, Leonid Rudy Softwareprodukte. All rights reserved.
To contact us, please visit www.filigris.com or e-mail to: contact@filigris.com