What's New in Javadoc 1.4

 Javadoc Tool

This document describes the changes made to the Javadoc tool between versions 1.3 and 1.4. You can also see a concise list of outstanding bugs listed at important new bugs and regressions, and can view listings from our database at Important Bug Fixes and Changes.

Summary of New Tags and Options

Here is a brief summary of the new tags and options.
New Tags
{@linkplain}, {@inheritDoc}, @serial, {@value}

New Options
-breakiterator, -docfilessubdirs -exclude, -excludedocfilessubdir -nocomment, -noqualifier, -quiet, -source, -linksource, -subpackages, -tag, -taglet

Possible Incompatibilities

The following changes can affect the way your existing doc comments are interpreted or displayed:

Running Javadoc

Includes changes that affect command line options, errors and warnings.
Added -subpackages option to recursively traverse all subpackages by passing in a single package root. The -exclude option unconditionally exclude packages from the list of packages to document even if it would otherwise be included by some previous or later -subpackages command-line flag. For example, -subpackages java -exclude java.lang.ref would include java.io, java.util, and java.lang (among others), but not java.lang.ref. (4074234)

Added "-source 1.4" option for assertions - This option documents code that was compiled using "javac -source 1.4", necessary for code that contains assertions. (4400430)

Added public methods to invoke Javadoc tool from within Java - Added a programmatic interface to the Javadoc tool in com.sun.tools.javadoc.Main (consequently, the standard doclet was made re-entrant). For more details, see Standard Doclet. (4113483)

Warning and error messages now contain filename and line number. The line number is to the declaration line rather than to the particular line in the doc comment. Uses the SourcePosition class. (4396665)

Serialized form page enhancements - Javadoc now includes private classes in the serialized form page (without requiring the -private flag). This means the serialized form page can be properly generated in a normal Javadoc run. This was done by adding the method PackageDoc.allClasses(boolean filter) where private and package-private classes are included when filter is false. () The method writeReplace() is now included in the serialized form page. Javadoc also now looks at "@serial include" and "@serial exclude" tags and includes or excludes classes accordingly. For more information, see @serial tag. (4290079, 4180839, 4341304)

Documented @files to work with command line options as well as filenames This changes the documentation to conform to the implementation. The @files feature was originally documented in javadoc and javac to allow only filenames, not command line options. This expands the documentation to say that @files also allows command line options. (Also renamed @files to @argfile in the documentation to make it clear it's a file of arguments.) (4469119)

Added -quiet option to shut off non-error messages
Only the warnings and errors appear, making them easier to find. (4217345)

The standard doclet prints its version number in its output stream. Suppressed by -quiet option. (4114089)

Automatically create destination directory (-d). Since a primary function of javadoc is to create files and directories, it seems reasonable to create the root destination directory as well. (4464477)

Document only legal classes - When documenting a package, Javadoc no longer reads files whose names are not composed of legal class names. Example: When passing com.sun.foo into Javadoc, it used to parse every file in the directory com\sun\foo whose name ended with ".java", whether or not the filename, stripped of that suffix, was actually a legal class name. Now Javadoc will parse only files whose names are legal class names. This enables developers to include templates, test source files, or other .java files that will not be documented, by including, for example, a hyphen "-" in its filename. (4398440)

Fixed -linkoffline separator '/' - When running on Microsoft Windows, the -linkoffline option now properly inserts '/' instead of '\' in each link that points to an external class. This bug caused broken links to external classes when documentation that was created by Javadoc on Windows was then browsed on Unix. (4359874)

Removed transitional "-1.1" option - The "-1.1" option was introduced in version 1.2 as a doclet to provide a transition path from Javadoc 1.1 to 1.2. This transition is not necessary for moving to 1.3. The "1.1" doclet did not handle new features of the language (such as inner classes) and because of shared code with the standard doclet was an impediment to maintenance. (4312499)

Writing Doc Comments

Includes changes that affect how doc comments are written, such as new tags.
Added tag interface for custom tags
You can create and use your own custom tags -- both normal standalone tags, similar to @return, and inline tags, similar to {@link}.

  • Simple tags - These are tags with a single text argument. You choose a unique name for a tag and use the -tag option.
  • Complex tags - These are tags with more than one argument, or that need special output. This requires developing a "taglet" class that implements the tag behavior. Then specify the -taglet and -tagletclasspath options (don't use the -tag option).
In both cases, the order of the -tag and -taglet options determine the order they are output. You can mix these options with the standard tags "-tag return", "-tag param" to intersperse them.

For custom inline tags, create a taglet. (4282805)

Flag any unknown tags while printing custom tags. This is a part of the custom tag mechanism. When javadoc parses the doc comments, any tag encountered that is not either a standard tag or passed in with -tag or -taglet is considered unknown, and a warning is thrown. (4039014)

When omitting the leading asterisk (*), keep indentation within <PRE> tags. This enables you to paste code examples directly into a doc comment. Indentation is relative to the left margin (rather than the separator /**). (4232882)

Added -breakiterator for new way to determine end of first sentence. We plan to change the algorithm for determining the end of the first sentence in the next major feature release. The -breakiterator option gives you a preview of the new algorithm. In 1.2 and 1.3, the java.text.BreakIterator class was used to determine the end of sentence for all languages but English (4165985). English had its own algorithm, which looked for a period followed by a space. When -breakiterator is omitted, the end of the first sentence is unchanged from 1.2 and 1.3, but warnings are emitted displaying where there would be a difference. Using -breakiterator uses the new algorithm. Differences in the algorithms show up in English as follows: (4165985)

  • Old algorithm - Stops at a period followed by a space or a paragraph-level HTML tag, such as <P>.
  • New algorithm - Stops at a period, question mark or exclamation mark followed by a space if the next word starts with a capital letter. This is meant to handle most abbreviations (such as "Serial no. is valid", but won't handle "Mr. Smith"). Won't stop at HTML tags or sentences that begin with numbers or symbols.

Fixed Javadoc to no longer require method bodies. - You can now run javadoc on .java source files that are pure stub files with no method bodies. This means you can write documentation comments and run Javadoc in the earliest stages of design while creating the API, before writing the implementation. Previously, javadoc complained if you tried to do this, insisting that you add "abstract" to the methods and the classes.

Added {@linkplain}, a plain text version of {@link}. The link's label is displayed in plain text rather than code font. Useful when the label is plain text. (4429628)
Example: 

        Refer to {@linkplain add() the overridden method}.

Added {@inheritDoc} tag for inheriting documentation. This tag copies the doc comment from a superclass into the current doc comment. This allows developers to write around the copied text rather than have the inherited text be the only text. Previously, text was copied only if the comment was missing. (4186639)

Javadoc tags @return, @param, and @throws are now individually inherited. In 1.3, they would be inherited only if the entire doc comment was empty. The @see tag is also inherited, but only if there are no @see tags in the overriding element. (4496270)

The @throws documentation is copied from an overridden method to a subclass only when the exception is explicitly declared in the overridden method. In 1.3, the @throws text would be copied to an overriding method, whether or not that method actually could throw that execption. This new behavior may remove some documentation that @throws was properly inheriting. You can use {@inheritDoc} to cause @throws to inherit documentation. (4317583)

Output Content

Includes output text, images, layout, formatting and links.
Includes values of static field constants - Javadoc now documents the values of constant fields. Those values appear on a separate Constant Values page, reachable from "See also: Constant Values" links by each static field. The new inline tag {@value}, when used in a static field comment, returns its value. This tag is useful for inserting the value into a doc comment. (4422788)

This change required adding to the Doclet API the methods FieldDoc.constantValue() and FieldDoc.constantValueExpression() in package com.sun.javadoc. () (4320557)

Added -noqualifier option to omit qualifying package name from ahead of class names in output
The previous behavior was as follows: On the page for class p.C, add the package name only to classes not belonging to package p. The argument to -noqualifier is either "all" (all package qualifiers are omitted) or a colon-separate list of packages, with wildcards, to be removed as qualifiers (such as "java.lang:java.awt:javax.*"). (4359889)

Add links to source code, using -linksource option
Creates an HTML version of each source file and adds links to them from the normal documentation. (Named -src in Beta 2. Will rename it to -linksource in the final version, to better differentiate it from -source.) (1242492)

Put current class or package name first in window title.
This enables the name to appear in the Windows task bar when a window is minimized. (Also works in Internet Explorer when frames are turned on.) (4232597)

Generate package page when passing in source filenames (*.java). The docs that are generated should not be any different when passing in package names than when passing in the source filenames for classes in those packages. (4359386)

Put exception class link in throws section in two cases:
(1) there a @throws tag but no text accompanies the tag
(2) if an exception is declared but there is no tag (4074202)

Added -nocomment to suppress description and tags, generating only declarations. Enables re-using source files originally intended for a different purpose. (4464558)

Error exit status - Fixed javadoc to use the exit status of the doclet. (4136558)

Use the -encoding option when reading package.html. (4463408)

Added "All Classes" to navigation bar for improved accessibility (4140824)

Directory doc-files is now copied when passing in .java files - When passing in source files (*.java) to Javadoc, it now copies the "doc-files" directories to the destination. (Formerly, the "doc-files" directories were not copied.) This behavior is now identical to that when passing in package names. (4340814)

Fixed doc-files directory at doc root to be copied to destination.
This enables the inclusion of overview-level documentation to be included. (4256505)

Added -docfilessubdirs to enable deep copy of doc-files - Subdirectories of the "doc-files" directory are now recursively copied to the destination when -docfilessubdirs is used. For example, doc-files/example/images and all its contents would now be copied.If you need it, this option is also available: -excludedocfilessubdir name1>:<name2>... to exclude any doc-files subdirectories with the given names. This prevents the copying of SCCS and other source-code-control subdirectories. Previously, only files directly in "doc-files" were copied. (4385048)

Fixed {@docroot} in HTML frame - The {@docroot} tag is now properly resolved when it appears in the upper left HTML frame (overview-frame.html). (4365290)

Fixed {@docroot} in @see - The {@docroot} tag is now properly resolved when it appears in the text of an @see tag. (4416364)

Fixed {@link} with {@docRoot} - The {@docRoot} tag no longer disables any {@link} tag that follows it in the same comment. (4369014)

"Implements" heading - A doc comment inherited from an abstract method now uses the proper subheading "implements" rather than "overrides". (4318787)

Fixed "Implementing Class" on interface page - Fixed bug on interface page where some classes were not showing up as "implementing class". (4378491)

Fixed display of static initializers - The initializer static {...} caused the "Methods Inherited From" table to start with a comma (,). The underlying bug was that javadoc considered static {} to be an anonymous method. It will no longer appear as a method entry in the generated docs. (4136861)

Properly document fields and methods for private inner classes. (445611)

Corrected "nested classes" terminology - Javadoc now uses the term "nested classes" rather than "inner classes" throughout its headings and subheadings. The definitions are: "A nested class is any class whose declaration occurs within the body of another class or interface." while "An inner class is a nested class that is not static." Therefore, "nested" is the more general term. (4307151)

Doclet API

Doclet API is no longer serializable. - The classes no longer extend serializable. (It would have been impossible, in general, to properly serialize them.) (4125581)

Expose filename and line number of declarations. A new class SourcePosition has been added to the Doclet API, as well as a new method position() in Doc and Tag (see 4192783). These enable the complete decomposing and recomposing of source files. (4192783, 4208989)

Added MethodDoc.overriddenMethod() for returning the list of methods that are overridden.

Improved documentation of the Doclet API.

Potential incompatibility - The Tag interface now has a position() method. Doclets that implement the 1.3 Tag interface (such as MIF Doclet 1.2 Beta 1) will not work with Javadoc 1.4.

Standard Doclet Code Change

Standard doclet code change - In the standard doclet source code, added a configuration argument to the MessageRetriever constructor signature. This may affect code that subclasses the standard doclet. New constructor is now MessageRetriever(Configuration configuration, String resourcelocation) (No bug number)

Javadoc Tool Front End

There are many changes to the Javadoc tool described in the other sections; the most notable one is mentioned here.

Complete reimplementation of the Javadoc tool and API (4400430): - Javadoc now uses the new javac compiler instead of the old.

A few changes in behavior are known. These are not bugs and will probably never be "fixed" in javadoc:

  • Private inner classes are now marked as private. The old javadoc incorrectly marked them as having package protection.
  • static class initialization blocks were reported by the old javadoc as if they were a function named <clinit>. The new javadoc correctly omits them.
  • The old javadoc incorrectly inserted a this$0 parameter to constructors for nested classes. While this agrees with the reflective view of these constructors, it is not correct from the source or the language viewpoint. The new javadoc reports the signature as it appears in the source.
  • The old javadoc sometimes reported the compiler-generated field this$0 as a serializable field. The new javadoc correctly omits mention of this$0 and other synthetic members. See java.util.logging.LogManager.LogProperties for an example.
  • The old javadoc occasionally omitted wildcard import declararations that appeared in the source. For example, in the translation unit for java.io.PipedOutputStream there is a (useless and redundant) "import java.io.*;". The new javadoc correctly includes this in the list of imports.
  • The old javadoc incorrectly reported that a private method overrides a private method with the same signature in the superclass. The new javadoc correctly reports that a private method is never overridden.
  • Some bugs remaining in the new java.io implementation prevent the correct processing of Unicode characters on output. While this is not a javadoc bug per se, it will affect any comparison of the old javadoc output with the new. For an example of the differences, see java.util.regex.Pattern.Caret. The workaround is to use a locale that supports a wider set of Unicode.

Some further known examples of incorrect behavior of the old javadoc are intentionally reproduced in the new javadoc implementation for compatibility. For example, if a class a.A has inner classes and you import them using: 

        import a.A.*;
Old Javadoc would incorrectly report (through the Doclet API) an import of: 
        import a.*;
There is no way of correctly expressing this import declaration with the current javadoc API.

ClassDoc instances are no longer unique - Prior to 1.4.0, every class being documented was represented by a single ClassDoc instance -- this was an undocumented implementation detail. With 1.4.0, this is no longer true -- the Javadoc tool is capable of creating two different ClassDoc instances that represent the same class. This would break any doclets that mistakenly relied on this fact. One such bug was 4496290: The -use option is severely broken.


Java Software