Javadoc 1.1 FAQ

Print-friendly Version

Javadoc FAQ

Javadoc 1.1 Only

Download the .gif images and "API users guide" file here (~24K). This latter file is named API_users_guide.html, which you access by clicking on the link "API User's Guide" in the upper left corner of the first page (packages.html). Please see the README. You can also obtain them from the docs/api/images/ directory in the downloadable JDK docs.

E2.   Is there a way for Javadoc 1.1.x to include the necessary .gif files with its output?

When I run javadoc, all the images (for headings and bullets) in the generated HTML files appear as broken links. Is there a way, other than manually copying the images, to get javadoc to include the necessary .gif files with its output?

No. Currently, you must copy the .gif files separately from running javadoc.

The .gif files reside in the api/images directory. To get the .gif files, download the JDK Documentation bundle and look in the docs/api/images directory. In your javadoc destination directory, create an images directory and copy the .gif files there.

You can automate this process by writing a batch file (or shell script) that runs javadoc and also copies the images to the destination directory.

Unnoticed by many people, when they do a javadoc build, there is another broken link "API User's Guide" in the upper-left corner of the packages.html page. This is a link to the file API_users_guide.html, which describes how the API docs are organized and includes the legend for the color-coded bullets. You must also copy this file over to the output destination.

We have improved Javadoc 1.2 and later versions to no longer require graphics. We have renamed API_users_guide.html to help.html, and there is a command line option to omit the link to it from the navigation bar. If you include the link, you must manually copy the file to the destination.

This capability has been added to Javadoc 1.2. In earlier versions of Javadoc, we added these headers and footers by running a script on the generated HTML files.

Javadoc didn't do this. We did this with the PERL script javadocindexsplit.pl, which we ran on Solaris using Perl 5.0. Feel free to use it.

Javadoc 1.1.x generates an index file "AllNames.html". This script does not modify the file "AllNames.html" itself, but copies its content into the files a-index.html, b-index.html, ..., y-index.html. (Unfortunately, javadoc 1.1.3 does not generate index entries for API names starting with "z". This is fixed in a later release.) To complete the job, you need to make the links that point to "AllNames.html" work instead with "a-index.html". The link "AllNames.html" appears at the top and bottom of most html pages, identified with the label "Index". You can do this in any of several ways:

• By deleting AllNames.html and creating a shortcut (symbolic link in Unix) from AllNames.html to a-index.html. For example:

  rm AllNames.html                                    (Unix)
  ln -s a-index.html AllNames.html
  

  delete AllNames.html                                    (Windows)
  shortcut -f a-index.html AllNames.html

• By copying "a-index.html" to "AllNames.html" so it exists with both filenames. For example:
  cp a-index.html AllNames.html                  (Unix)
  copy a-index.html AllNames.html            (Windows)

• By changing the links in the HTML web pages themselves from "AllNames.html" to "a-index.html":
  % perl -pi.bak -e "s/AllNames.html/a-index.html/g" *.html
  You can then delete "AllNames.html" to free up disk space.

This has been fixed in Javadoc 1.2. This will not be fixed in any 1.1.x version of Javadoc.

WORKAROUND - There is no known workaround.

This is a bug where javadoc appears to run successfully, but the index page is blank except for the header and title at the top of the file. This happens in two cases we have identified:

• If a class has a public or protected member that begins with a non-alphabetic character (such as underscore "_"). For example:

      public class Foo 
      {
           protected int _d;
      }
  

• If a class contains a static initializer method. Since there is no method declaration, it confuses Javadoc.

      public class Goo {
           static { System.out.print("Initializing"); }
      }
  

WORKAROUND - Switch to Javadoc 1.2, which fixes this problem. This is fixed in the default 1.2 output and with the -1.1 option of Javadoc 1.2. The -1.1 option generates the 1.1 look with the 1.1 flat destination file structure.

If you must use Javadoc 1.1.x, one poor "workaround" is to temporarily remove the keyword "public" or "protected" (so that javadoc won't try to document that member, but will generate the index without it) or remove the leading non-alphabetic character. We have no plans to fix this bug in future 1.1.x versions of Javadoc.

The -private, -protected and -package options were introduced in JDK 1.1.2. These options work properly on members of a public class, but unfortunately have never worked properly on members of non-public classes. Therefore, only comments for public classes and any of their members can be generated. Instead of generating the doc comments, it generates this message:

This class is not public and therefore cannot be used outside this package.

This bug has been fixed in Javadoc 1.2. This bug will not be fixed in any JDK 1.1.x version of javadoc.

WORKAROUND - Switch to Javadoc 1.2. Otherwise, ugly though it may be, you can change all classes to "public" in the source code, generate the docs, and then selectively remove the word "public" from the generated docs. This last step requires selectively searching for:

"<dl>
  <dt> public " 

and replacing it with:

"<dl>
  <dt> "

Brian Erwins has written a "fixpublic" script that runs on Solaris with Perl 5. This script both adds "public" to the source files and removes "public" from the proper places in the generated HTML files. This script has some Unix dependencies.

The javadoc reference page says under "Documenting One or More Packages" that you can run javadoc without -sourcepath. However, this doesn't work in JDK 1.1.x due to a bug in javadoc.

WORKAROUND - Include the sourcepath option with a "dot" (.) for the current directory:

javadoc -d html -sourcepath . java.awt

Using a URL in an @see tag does not work in Javadoc 1.1.x, but works in 1.2:

      @see <a href="/j2se/javadoc/faq/1.1/spec.html">Java Spec</a>

In 1.1.x, it generates the error: "Extraneous text following reference."

Other forms of the @see tag documented in the Java Language Specification also do not work in 1.1.x, though we have not enumerated them here. (Anyone who can add to this list, please let us know.)