Cannot find doclet class com.docflex.javadoc.DocletThis 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:
-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.
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.
docflex-javadoc.jar
or docflex-doclet.jar
file.
For more details, see
Documentation | Integrations | Eclipse.
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:
javadoc -J-Xmx512m ...
project/package summary seems to be missing using DocFlex Docletor that
If you have this kind of problem, please understand the following basic things:overview.html
andpackage.html
files are ignored
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
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
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.
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.
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:
Then, specify location of this file in the “HTML pattern file” field within the HTML Options dialog (or using<!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>
'-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 <!-- docflex-html-head -->
and
<!-- docflex-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
<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.
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.
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 TextIn 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).
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. |