This happens because Javadoc cannot find the docflex-javadoc.jar or docflex-doclet.jar file (depending on the edition you use), which contains the DocFlex Doclet executable classes.

Please, check the following:

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 {docflex-javadoc}\lib\docflex-javadoc.jar
where {docflex-javadoc} is the absolute pathname of your DocFlex/Javadoc installation directory.
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.
If you run Javadoc from Apache Maven, make sure that either docflex-javadoc.jar (or docflex-doclet.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.
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 docflex-javadoc.jar or docflex-doclet.jar file. For more details, see Documentation | Integrations | Eclipse.

DocFlex doclet is too slow

You are running Javadoc with DocFlex 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 DocFlex 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.

DocFlex 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 DocFlex Doclet) that it must use 256-512 MB heap size. How to specify this depends on where you run Javadoc:

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-Xmx512m ...
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.
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.
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 DocFlex Doclet

or that

overview.html and package.html files are ignored

If you have this kind of problem, please understand the following basic things:

The project overview (which appears on the standard JavaDoc front page) is obtained from the overview.html (or any other HTML file) specified with -overview option on the Javadoc command-line. This is one of the core Javadoc options never processed by any doclet!
See also: ORACLE.COM | Javadoc Reference Guide | Source Files | Overview Comment File
The package descriptions are not specified with any options. Rather they are found in the package.html files placed in the package directories themselves.
Under Java 5, instead of package.html you may also use package-info.java file. The main difference is that it may include annotations.
See also: ORACLE.COM | Javadoc Reference Guide | Source Files | Package Comment Files
Both overview.html and package.html/package-info.java files are never processed by any doclets!
Rather, they are picked up and processed by the Javadoc core itself. Then, the content of those files is just provided via Doclet API, as any other Javadoc comments.

So, if you do not see some of your project/package summaries in a JavaDoc generated using DocFlex Doclet, please do not hurry to blame our tool. Rather, check your settings again!

For example, here is what one our user found eventually (and reported to us):

The problem was simple, I created the package.html files in another workspace [Eclipse]. So it was my fault. Now it works as expected. Thank you for your help.

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, DocFlex/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>
<!-- docflex-html-head -->
</HEAD>
<BODY>
<!-- docflex-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).

DocFlex will produce all HTML documents using the specified HTML pattern file with the lines  and  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 DocFlex/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 DocFlex 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\\PlainDoc.rtf" \* MERGEFORMAT }

Here, the RTF document generated with DocFlex should be found by the path:

C:\blah\blah\PlainDoc.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 DocFlex 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 OpenOffice.org

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

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

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.