当前页面:
在线文档首页 >
JDK 5 Documentation v6.0, Java 2 SDK 英文文档
What's New in Javadoc 5.0 - JDK 5 Documentation v6.0, Java 2 SDK 英文文档
This document describes the changes made to the Javadoc tool between
versions 1.4.2 and 5.0 (formerly 1.5.0).
The changes listed below include the bug number and whether the
fix was in the Javadoc tool front end ("tool") or standard doclet
("stddoclet"). The term "regression" appears for features that
regressed at some point -- usually for features that worked in 1.3.x,
broke in 1.4.x, and have been fixed in 5.0.
Notable New Features
Notable Bug Fixes
Known Bugs
Javadoc 5.0 has no known bugs that cause it to hang or crash.
You can view listings from our database at Bug Parade as described at:
Javadoc FAQ.
The notable bugs are:
- Six-fold performance degradation since 1.4.2 for deeply inherited classes.
The slowdown is partly due to the extra processing required by generic
type parameters.
Workaround: None.
(5081166)
- @param in base class is ignored if {@inheritDoc} in main description.
Workaround: None. (4778311)
- Produces faulty Constant Values page if a constant contain angle bracket '<'
Workaround: None.
(5077317)
- Malformed HTML tag throws error due to message not found in resource file.
Error message: java.util.MissingResourceException: Can't find resource for bundle com.sun.tools.doclets.formats.html.resources.standard, key doclet.malformed_html_link_tag
Workaround: Reduce the number of packages and classes passed into javadoc until the
error goes away and you locate the source file that contains the malformed tag.
Then fix the malformed tag. A malformed HTML tag is one that begins properly but
is otherwise improper. For example <action>
is interpreted as a malformed <a> tag.
(5082928)
Incompatibilities with Custom Doclets
Custom doclets written prior to 5.0 will have compatibility
problems when run on source files that use new language features in 5.0.
- New Language Features:
The Doclet API and standard doclet were revised to handle
the new 5.0 language features
-- generics, enums, varargs and annotations. To handle these
features, custom doclets would also need to be revised.
The Javadoc tool tries -- to the extent possible -- to present
so-called "legacy" doclets with a view of the program that
1) continues to work with pre-5.0 source code, and 2) matches
their expectations for 5.0 source code. So, for example, type
parameters and type arguments are stripped from generic
constructs, type variables and wildcard types are replaced by
their erasures, and ClassDoc.fields()
will
return enum constants.
But legacy support is not specified with precision. It's
a compatibility mode that will suffice until the doclet gets updated
to understand the language it is operating on. The only guarantee
is source and binary compatibility of doclets themselves:
when using the 5.0 Javadoc tool, if your doclet is based on 1.4
and the source code on which you're operating is also based on
1.4, then you can still compile the doclet and it will still
operate as before (modulo bug fixes).
New Features and Bug Fixes
The following is a list of essentially all new features and bug fixes
in 5.0. Only very minor changes are omitted (such as fixing broken
links in the documentation for the Doclet API) and bugs introduced in
early-access releases of 5.0 but fixed in the final release are omitted.
Command Line Options
- New feature: New -keywords option adds HTML meta tags
to each generated file to help with search
(4776637, stddoclet)
- New feature: New -notimestamp option suppresses hidden timestamp
embedded near the top of HTML pages
(4777717
- New feature: It is now possible to create test subpackages
that contain hyphens that the -subpackages option will skip over
without producing warnings. That is, this option will no longer
warn if it encounters a directory with an illegal Java name
(which is consistent with illegal source filenames).
(4773013, tool)
- Bug fix: The -help option no longer mistakenly shows "[classnames]"
in the usage.
(4775743, tool)
- Bug fix: The -group option no longer causes a duplicate warning.
(4924383, stddoclet)
Tags and Taglets
- New feature:
The {@literal} tag denotes literal text. The enclosed text is
interpreted as not containing HTML markup or nested javadoc tags.
For example, the doc comment text: {@literal a<B>c} displays in
the generated HTML page unchanged: a<B>c -- that is,
the <B> is not interpreted as bold.
- New feature:
The {@code} tag formats literal text in the code font.
It is equivalent to <code>{@literal}</code>.
- New feature: The {@value} inline tag now accepts the name of
a program element and label:
{@value package.class#member label}
.
This enables it to be used in any doc comment.
(4764045, stddoclet)
- New feature: Not a Javadoc tag, the @Deprecated annotation is new
in 5.0 and should be used in addition to the
@deprecated
tag
for deprecating program elements.
See @Deprecated annotation.
- Bug fix: (regresion): Fixed @param so the parameter name (its first
argument) is printed even if incorrect, as it worked in 1.3.1.
(4802275, stddoclet)
- Bug fix: (regression) Fixed -tag so its name can once again contain
a dash "-", as was allowed in 1.4.1.
(4920381, stddoclet)
- Bug fix: A first sentence containing a {@docRoot} link is no longer
broken in the single-page index.
(4760191, stddoclet)
- Bug fix: The end of a first sentence containing {@inheritDoc} is
now determined correctly.
(4767038, stddoclet, 4 votes)
- Bug fix: Use of the {@docroot} tag in -bottom text no longer causes
a broken link on the help-doc.html page.
(4851991, stddoclet)
- Bug fix: Modified taglet code to allow standalone tags to handle inline
tags.
(4654308, stddoclet)
- Bug fix: Use of {@value} in a custom tag no longer generates a
NullPointerException.
(4821796, stddoclet)
- Bug fix: Inline tags now allow nested braces that do not belong
to inline tags.
(4965490, tool)
- Bug fix: @param, @return and some @throws tags now inherit comments properly.
(4915434, stddoclet)
- Bug fix: @throws documentation is now auto-inherited if the exception
is checked.
(4947455, stddoclet)
Links
Documented Source files
- New feature:
package-info.java
is a reserved name
for a source file to store package comments and annotations.
package-info.java
is described above.
Generated API Specifications
- New feature: Added support for generics, enums, and varargs
in the javadoc tool front-end (Doclet API)
(4421066, tool)
and standard doclet
(4789689, stddoclet)
- New feature: Added support for annotations and annotation types
in the javadoc tool front-end (Doclet API)
(4904495, tool)
and standard doclet
(4905985, stddoclet)
- New feature: For legibility, constant field values
of type long are now printed with "L" rather than lowercase "l".
(4869993, tool)
- New feature: For legibility, serialVersionUID values
of type long are now printed with "L" rather than lowercase "l".
(4821483, stddoclet)
- New feature: Table of contents has been added to the
top of the "Deprecated" list.
(4927552, stddoclet)
- Bug fix: No longer hangs when {@inheritDoc}
(1) cannot inherit or (2) inherits from super-superinterface.
(4812240, stddoclet)
- Bug fix: Inherited non-public superclass is no longer mentioned
(4874845, stddoclet)
- Bug fix: "Specified by:" and "Overrides:" comments are now
inherited from externally referenced classes.
(4857717, stddoclet)
- Bug fix: Documentation is no longer inherited from members
of package-private classes.
(4780441, stddoclet)
- Bug fix: Order of method descriptions can no longer change from one
run to the next.
(4885372, stddoclet)
- Bug fix: When class B extends class A which implements interface I,
in the documentation for I, we now document that B implements I
(under "All implementing classes").
(4947464, stddoclet)
- Bug fix: Correct return type now shows up in member summary
when a method inherits documentation from an overridden method
that returns a different type.
(4951228, stddoclet)
- Bug fix: Now generates doc for readObjectNoData() in serialized form
page.
(4770063, stddoclet)
- Bug fix: Now generates a package summary page for the unnamed package,
if present.
(4774450, stddoclet)
- Bug fix: Now prints "Unnamed" as the name of the unnamed package,
rather than printing empty string.
(4904075, stddoclet)
- Bug fix: All inherited methods from multiple extended interfaces
are now documented.
(4933335, stddoclet)
- Bug fix: Interface methods are no longer marked "public" (just a
change -- not actually a bug).
(4682448, stddoclet)
- Bug fix: Constructor comments are now indented properly.
(4904037, stddoclet)
- Bug fix: packages.html (note the plural) file is no longer included,
as it has not been used or needed since 1.1.
(4475679, stddoclet)
- Bug fix: When a type parameter in the member summary is greater than
10 characters, now add a line break to shorten it
(4927167, stddoclet)
Formatting and Invalid HTML
- Bug fix: Now outputs <NOSCRIPT> tag with each <SCRIPT> tag.
(4855054, stddoclet)
- Bug fix: Internet Explorer no longer displays an unnecessary
horizontal scroll bar when frames are showing.
(4852280, stddoclet)
- Bug fix: Newlines are no longer hard-coded as "\n".
(4938109, stddoclet)
- Bug fix: Table border added around class headings in constant value
summary.
(4904025, stddoclet)
- Bug fix: Now prints certain HTML source comments conditionally
(4904038, stddoclet)
Navigation Bar
- Bug fix: An extra column no longer appears in the first row of
the navbar.
(4664607, stddoclet, 1 vote)
- Bug fix: Package link is now active when documenting only one
package.
(4689286, stddoclet)
- Bug fix: Next/Prev Class links now iterate through all interfaces
and classes in current package.
(4131628, stddoclet)
Accessibility
- Bug fix: Table headings now use
rather than | .
(4905786, stddoclet)
- Bug fix: Missing space added at end of alternate text for inherit.gif.
(4956908, stddoclet)
Running Javadoc
- Bug fix: No longer get InvocationTargetException when a source
flie links to another source file in the wrong directory.
(4835749, stddoclet)
- Bug fix: (regression) No longer fails on internal classes,
as it worked in 1.4.1.
(4843578, tool)
Error/Warning/Notice Messages
- New feature: Now warns when @return tag is present in void method.
(4490068, stddoclet)
- New feature: Now displays message when creating new
destination directory
(4657239, stddoclet)
- Bug fix: BreakIterator warnings no longer appear. For more
information, see above.
(4959985, tool)
- Bug fix: The "first sentence" warning is no longer split between stderr
and stdout.
(4753853, tool)
- Bug fix: DocLocale.java implementation has been modified to allow for
proper translation.
(4780921, tool)
- Bug fix: Now uses DocletErrorReporter to print option errors,
rather than MessageRetriever.
(4927928, stddoclet)
- Bug fix: Message no longer says "error" when it's really a warning
for a missing package-list file.
(4625883, stddoclet)
Doclet API
- New feature: Added support for generics, enums, and varargs
in the javadoc tool front-end (Doclet API)
(4421066, tool)
and standard doclet
(4789689, stddoclet)
- New feature: Added support for annotations and annotation types
in the javadoc tool front-end (Doclet API)
(4904495, tool)
and standard doclet
(4905985, stddoclet)
- New feature: Add Doclet.languageVersion method to determine which
version of Java source code the doclet was written for.
(4909767, tool)
Standard Doclet Implementation
- Bug fix: Re-implemented standard doclet to maximize shared
code for doclets emulating the stddoclet
(4638723, stddoclet)
|