FlexDoc/Javadoc - Frequently Asked Questions

  1. Troubleshooting
  2. HTML Output
  3. RTF Output

1. Troubleshooting

There are few (but frequent) situations where we can immediately suggest how to fix your problem.

Cannot find doclet class

You are trying to run Javadoc with FlexDoc Doclet and receive an error:
Cannot find doclet class xyz.flexdoc.javadoc.Doclet
This happens because Javadoc cannot find the flexdoc-javadoc.jar file that contains FlexDoc Doclet executable classes.

Please, check the following:

  1. If you run Javadoc from the command line (or command file), make sure that -docletpath option is specified properly and points to the location of one of the above jar-files. For example:
    -docletpath {flexdoc-javadoc}\lib\flexdoc-javadoc.jar
    where {flexdoc-javadoc} is the absolute pathname of your FlexDoc/Javadoc installation directory.
  2. If you run Javadoc from Apache Ant, make sure that both name and path attributes of <doclet> element are specified properly. For more details, see Documentation | Integrations | Apache Ant.
  3. If you run Javadoc from Apache Maven, make sure that flexdoc-javadoc.jar has been installed into the Maven repository and you have properly specified <doclet> and <docletArtifact> elements in your project POM file. For more details, see Documentation | Integrations | Apache Maven.
  4. If you run Javadoc from Eclipse, make sure that the field «Use Custom Doclet | Doclet class path» in the «Generate Javadoc» dialog is specified with the absolute pathname of flexdoc-javadoc.jar file. For more details, see Documentation | Integrations | Eclipse.

FlexDoc doclet is too slow

You are running Javadoc with FlexDoc Doclet and it seems working too slow.

If you are not trying to generate the documentation for many thousands Java classes (or running everything on an outdated computer), most likely you have forgotten to specify enough memory for Javadoc.

The same is true even when FlexDoc Doclet is not involved at all. You may run Javadoc with the Standard Doclet (that is without specifying any doclets) on a rather big project and it may become very slow too. The cause is the same – the lack of memory!

Now, you may wonder. You have a lot of RAM installed on your system, e.g. a couple of gigabytes (or even more). Is it not enough?

The problem is that without specifying that memory explicitly, JVM does not use it. By default, JVM will allocate a heap of 64 MB size and that will be all the memory available to any Java application executed by that JVM!

When the application is memory-intensive, it will be allocating lots of objects, discarding some of them later, allocating new ones and so on. When the memory heap is small, JVM will run the memory garbage collection procedure too frequently. It may be resolving eventually each memory request coming from the application. But that will cost many extra operations. Effectively, JVM may end up doing the garbage collection almost all the time. That's why everything gets so slow! If at some point JVM is unable to allocate a necessary memory block it will throw java.lang.OutOfMemoryError exception.

FlexDoc Doclet does need memory! First, it needs memory to maintain the virtual XML-like representation of the Doclet API (see Doclet DSM). Additionally, it uses lots of hash-tables to boost performance. So, the default 64 MB heap size is almost never enough.

What you need to do is to notify the JVM (that will run Javadoc with FlexDoc Doclet) that it must use 1-4 GB heap size. How to specify this depends on where you run Javadoc:

  1. If you run Javadoc from the command line (or command file), make sure that -J-Xmx option is specified with sufficient amount of memory. For example:
    javadoc -J-Xmx2048m ...
  2. If you run Javadoc from Apache Ant, make sure that maxmemory attribute of <javadoc> element is specified with proper memory size. For more details, see Documentation | Integrations | Apache Ant.
  3. If you run Javadoc from Apache Maven, make sure that you have specified <maxmemory> element with enough memory size in the Javadoc plugin configuration of your project POM file. For more details, see Documentation | Integrations | Apache Maven.
  4. If you run Javadoc from Eclipse, make sure that -J-Xmx option is properly specified in «VM options» field of «Generate Javadoc» dialog. For more details, see Documentation | Integrations | Eclipse.

Missing overview and package summaries

From time to time, we regularly receive complaints like:
project/package summary seems to be missing using FlexDoc Doclet
or that
overview.html and package.html files are ignored
If you have this kind of problem, please understand the following basic things:

2. HTML Output

Inserting "Mark of the Web" comment

When you run generated HTML documentation from a local drive using Internet Explorer with Windows XP SP2, the Information Bar may indicate that active content (the JavaScript in the HTML) has been blocked. To avoid this problem, according to Microsoft, a Mark of the Web (MOTW) comment should be inserted in all generated HTML documents.

Since version 1.3, FlexDoc Doclet is able to insert the generic MOTW automatically (see code below). This is controlled by "Add Mark of the Web" option (see HTML Options dialog).

You may also program inserting MOTW by yourself using a special HTML pattern file. To do so, you should create a separate HTML file with the following content:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!-- saved from url=(0014)about:internet -->
<HTML>
<HEAD>
<!-- flexdoc-html-head -->
</HEAD>
<BODY>
<!-- flexdoc-html-body -->
</BODY>
</HTML>
Then, specify location of this file in the «HTML pattern file» field within the HTML Options dialog (or using '-o html.documentPatternFile' formatting option on the Javadoc command line).

FlexDoc will produce all HTML documents using the specified HTML pattern file with the lines <!-- flexdoc-html-head --> and <!-- flexdoc-html-body --> replaced with the actual generated output.

For more information about MOTW, please see Microsoft MSDN web-site. They frequently change the page location, so here is a Google query: http://www.google.com/#q=Mark+of+the+Web

3. RTF Output

Getting your images into RTF

Since FlexDoc/Javadoc version 1.4.7, any your images embedded in Java comments using <IMG> tags will be picked automatically from their original locations, where you have prepared them for the standard Javadoc, and inserted into the generated RTF.

Updating RTF fields in MS Word

The RTF documentation generated by the provided templates heavily uses document fields (for such things like page number references, number of pages and so on).

When you load the generated RTF in MS Word, to have the fields display the correct values, you will need to update them. To do this, please type: Ctrl+A, then F9.

Including RTF in larger MS Word document

Your task is the following. You have prepared a certain static Word document and need to include into it the output generated with FlexDoc so as each time your Java API documentation is regenerated, the larger Word document is updated as well.

Here is how you can do that.

You should insert into your Word document an INCLUDETEXT field. Using the MS Word menu, it may be done like this:

Insert | Field... | Categories: Links and References | Field names: Include Text
In the Word document (when “Toggle Field Codes” switched on), the field will look like the following:
{ INCLUDETEXT "C:\\blah\\blah\\SingleDoc.rtf" \* MERGEFORMAT }
Here, the RTF document generated with FlexDoc should be found by the path:
C:\blah\blah\SingleDoc.rtf
Make sure you use double slashes in the field's pathname (as a single slash is used to start a command or an option)!

After that, you can generate with FlexDoc the JavaDoc RTF. To prepare the result big document, open it with MS Word. Then, press Ctrl+A (select all) and F9 (to update fields).

Generating RTF for LibreOffice

Since FlexDoc/Javadoc version 1.4, you can launch FlexDoc/Javadoc under Linux (both Template Designer and FlexDoc Doclet).

The RTF generated by FlexDoc/Javadoc may be open with Linux OpenOffice.org Writer, which renders it almost the same as MS Word (see Samples | RTF in LibreOffice).

To make the RTF look better under OpenOffice.org, before generating it, please uncheck “Tune output for MS Word” option in RTF Options dialog (or using '-o rtf.tuneForMSWord=false' formatting option on the Javadoc command line).

Here are the details about this option:

When “Tune output for MS Word” option is selected, the generator will adjust some RTF formatting settings specifically for MS Word.

Although Microsoft is the originator of RTF format, the MS Word itself appears to have some oddities of rendering certain RTF settings, even though those settings may well follow the RTF specification. For instance, when displaying the paragraph or table borders, their horizontal positions may be shifted (e.g. when MS Word interprets horizontal margins of a paragraph, it draws the paragraph borders and paddings within the specified margin space but not within the paragraph content as it might be natural).

To overcome this, in such cases, we adjust the initial dimensions in the opposite way so as the result formatting would look properly in MS Word (e.g. to make the actual paragraph margin look as intended the margin width specified in RTF is increased by the paragraph border and padding widths).

However, when you generate RTF to display it primarily not in MS Word but rather in different viewers or editors (e.g. OpenOffice.org under Linux), which interpret the original RTF specification more literally, those specific adjustments may cause a visible distortion of the intended formatting of the document.

In such cases, we recommend to uncheck this option.