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 in Release Notes for Java SE 1.4.2, and view importatn bug fixes and changes in Bug Fixes in Subsequent 1.4.2 Update Release Versions.
{@linkplain}, {@inheritDoc}, @serial, {@value}
New Options
-breakiterator,
-docfilessubdirs
-exclude, -excludedocfilessubdir
-nocomment, -noqualifier, -quiet, -source, -linksource, -subpackages, -tag, -taglet
-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 Solaris, Linux, or Mac OS X.
(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)
@return, and inline tags,
similar to {@link}.
-tag
option.-taglet and -tagletclasspath options
(don't use the -tag option).-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, you must 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)
<P>.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)
{@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 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.
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)
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:
<clinit>. The new javadoc correctly omits
them.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.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.java.io.PipedOutputStream there
is a (useless and redundant) "import java.io.*;". The
new javadoc correctly includes this in the list of imports.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.
