Java Enhancements in Javadoc, Java SE 1.4.2（JDK8）

163 阅读 0 评论 0 点赞

Enhancements in Javadoc, Java SE 1.4.2

This document describes the changes made to the Javadoc tool between versions 1.4.1 and 1.4.2.

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 -- for features that worked in 1.3.x, broke in 1.4.0 or 1.4.1, and have been fixed in 1.4.2.

Notable New Features
Notable Bug Fixes
Notable Known Bugs
New Features and Bug Fixes

Notable New Features

All known bugs related to the U.S. Government's Section 508 requirements for accessibility have been fixed in this version. (4737558, stddoclet)
Include serialVersionUID in Serialized Form (4525039, stddoclet)
Can now inherit comments from source files not being documented. Your code can automatically inherit comments from interfaces and classes whose source files are on -sourcepath but are not being passed in on the command line. For example, for J2SE, You can do this by unzipping the src.zip file that ships with the SDK (which does not contain all source files, however), and add its path to -sourcepath. When javadoc runs on your code, it will load the doc comments from those source files as needed. For example, if a class in your code implements java.lang.Comparable, the compareTo(Object) method you implement will inherit the doc comment from java.lang.Comparable. This feature was actually available in 1.4.1. (No bug number, tool)
When using the -link (or -linkoffline) option, all @see and {@link} tags now create links to excluded classes. This fix greatly simplifies the ability to link to external classes and members. Previously, an external class needed to be either imported or fully qualified in a declaration in order for @see or {@link} to link to its documentation. Now, the only requirements are that the class be fully qualified and that its API docs appear on the path supplied by -link. (4652655, stddoclet)
Other new features are listed below.

Notable Bug Fixes

Links: Fixed @link of a fully-qualified program element to link to external classes with the -link option. (4652655, tool, REGRESSION)
Links: Fixed missing internal links on return/parameter types when .java files are passd in (4628281, tool)
Execution: Fixed so duplicate classes are documented (4673477, tool, REGRESSION)
Serialized form: Fixed link anchors to classes in serialized form (4521661, stddoclet)
Javascript: Internet Explorer Javascript load error when linked by -linkoffline (4645058, stddoclet, REGRESSION)
HTML: Fixed so there is no diff when passing in package names or .java file names (4506980, stddoclet)
Other bug fixes are listed below.

Notable Known Bugs

Bugs that can hang the Javadoc tool and highly noticeable bugs are listed here. You see a concise list of bugs listed at important new Javadoc bugs and regressions, and can view listings from our database at Important Bug Fixes and Changes.

Javadoc hangs without any useful message if {@inheritDoc} is used in a member that cannot inherit a comment. (4812240, stddoclet) For example:
```
public class C {
    /** {@inheritDoc} */
    public abstract void m() {
    }
}
```
Internet Explorer displays unnecessary horizontal scroll bar in the main content pane when frames are showing. A simple workaround is described in the bug report. (4852280, stddoclet)

New Features and Bug Fixes

All new features and bug fixes in 1.4.2 follow.

Command Line Options

New feature: Added -packagesheader option for upper left frame (4766385, stddoclet)
New feature: Enable "-tag name" shortcut for "-tag name:a:name" (4695326, stddoclet)
New feature: Added -linksourcetab option to convert each tab to n spaces. This option is experimental and may change. (4510979, stddoclet)
New feature: The -tag option now allows dash (-) separator for xdoclet tags like @ejb:bean (4750173, stddoclet)
New feature: New -keywords option adds member names as meta keyword tags to improve API search (4764726, stddoclet)
New feature: Added -Xwerror flag to exit nonzero if there are warnings. (4099527, tool)
Bug fix: Fixed option -tag tagname:X:taghead so it no longer requires taghead (4628181, stddoclet)
Bug fix: Documented -quiet option to quiet only the standard doclet messages (4714350, stddoclet). Opened a new bug 4702454 to request that it quiet the javadoc tool messages as well.
Bug fix: Moved documentation for -source option from doclet options to javadoc tool options -- it has always been a tool option (4760924, stddoclet)

Tags

New feature: Javadoc now inherits @throws comments for runtime exceptions (4679573, stddoclet)
New feature: Javadoc now warns when first argument of @param is not parameter name (4693440, stddoclet)
Bug fix: Now compares fully qualified exception names when inheriting @throws text (4684827, stddoclet)
Bug fix: Fixed missing 'Throws' heading when followed only by auto-generated exceptions (4530727, stddoclet)
Bug fix: Fixed broken @inheritDoc when inheriting from abstract superclass's interface (4720974, stddoclet)

API Specifications

New feature: Now includes serialVersionUID in Serialized Form (4525039 stddoclet)
New feature: Can now inherit comments from source files not being documented. Your code can automatically inherit comments from interfaces and classes whose source files are on -sourcepath but are not being passed in on the command line. See example. (No bug number, tool)
Bug fix: Fixed missing inherited nested classes from summary table (4638588, stddoclet)
Bug fix: Fixed so javadoc no longer incorrectly lists hidden fields (4492178, stddoclet)
Bug fix: Added serializable superclass of non-public serializable class (4671694, stddoclet)
Bug fix: No longer documents override of private method, such as createBufferStrategy (4634891, stddoclet)

HTML & Javascript

New feature: Now includes javadoc version number and build in generated HTML comment (4749707, stddoclet)
Bug fix: Added "#anchor" names back to links that point to classes in serialized form page (4521661, stddoclet, REGRESSION)
Bug fix: Fixed Javascript IE load error when linked by -linkoffline (4645058, stddoclet, REGRESSION)
Bug fix: Fixed so there is no diff when passing in package names or .java file names (4506980, stddoclet)
Bug fix: Fixed invalid stylesheet.css file (font-size: normal) (4417174, stddoclet)
Bug fix: Fixed window title to not change when loading left frames (javascript, stddoclet) (4747738, stddoclet)

Invalid HTML

Bug fix: Added missing whitespace in DOCTYPE declaration (4625400, stddoclet)
Bug fix: Fixed invalid HTML in frameset DTD and extra <DL> (4275630, stddoclet)
Bug fix: Fixed <NOFRAMES>, which is not allowed outside <FRAMESET> element (4753048, stddoclet)
Bug fix: Fixed wrong !DOCTYPE in index-all.html file (4418115, stddoclet)
Bug fix: Fixed HTML table tags that were inserted in wrong place in package use page (4415270, stddoclet)

Links

Bug fix: Internal links missing from return/param types when .java files passd in (4628281, tool, REGRESSION)
Bug fix: Fixed @link of a fully-qualified program element to link to external classes with the -link option (4652655, tool, REGRESSION)
Bug fix: Fixed -link and -linkoffline to create proper relative links (4720957, stddoclet)
Bug fix: The -linksource option no longer produces '\' in links when run on Windows (4511110, stddoclet)
Bug fix: The label in {@link java.lang label} is no longer ignored when linking to a package name (4524136, stddoclet)
Bug fix: @link tag no longer malformed when only newline exists between first and second arguments (4739870, stddoclet)

Running Javadoc

Bug fix: No longer crashes when test file of unnamed package was included in source directory (4670772, tool)
Bug fix: Fixed so duplicate classes are once again documented (4673477, tool, REGRESSION)
Bug fix: Empty jarfile on classpath: Fixed so empty jarfile in classpath no longer throws an exception (4697113, stddoclet)
Bug fix: Files: When source and destination directories are the same, doc-files are no longer trashed (4258405, stddoclet)

Error/Warning Messages

Bug fix: Improve unhelpful error message "foo.jar: Body tag missing from HTML" (4691095, stddoclet)
Bug fix: Fixed so javadoc no longer reports errors when classpath jar files contain package.html files (4697040, stddoclet)
Bug fix: Fixed erroneous "Parameter foo is documented more than once." warnings. (4745855, stddoclet)
Bug fix: Now uses Messager printwriters inead of System.out and System.err (4644257, stddoclet)

Accessibility

Bug fix: Add title description to links describing italic style as "interface" (4714257, stddoclet)
Bug fix: Added ability to skip over nav bar for accessibility (4638136, stddoclet)
Bug fix: Added "summary" attribute to tables for accessibility (4637604, 4775148, stddoclet)
Bug fix: Added title attribute to <FRAME> tags for accessibility (4636655, stddoclet)
Bug fix: Put <H1>, <H2>, <H3> in proper sequence (4636667, stddoclet)
Bug fix: Add text equivalent of ASCII art in class tree for accessibility (4706779, stddoclet)

Doclet API

New feature: Extended Doclet API with holder() method in Tag interface (4706525, stddoclet)
Bug fix: Doc objects are once again == comparable (4731054, tool, REGRESSION)
Bug fix: Fixed bad ClassDoc for nested classes when built from .class files (4694497, tool)
Bug fix: Clarified the specification for Doc.position() (4748246, stddoclet)
Bug fix: Clarified the specification for RootDoc classes() method (4748234, stddoclet)
Bug fix: Clarified the specification for com.sun.javadoc.SeeTag (4754029, stddoclet)
Bug fix: Clarified the specification for PackageDoc.ordinaryClasses() needs clarification (4748244, stddoclet)
Bug fix: Clarified the specification for "kind" in com.sun.javadoc.Doc (4502589, stddoclet)
Bug fix: Clarified the specification for Doc.isClass() and all "class" references (4748245, stddoclet)
Bug fix: Clarified the specification for "class" further (4763596, stddoclet)
Bug fix: Clarified the specification for PackageDoc.allClasses() method and the term "included" (4748240, stddoclet)
Bug fix: Clarified the specification for ProgramElementDoc.qualifiedName() parameter list (4621267, stddoclet)
Bug fix: Clarified the specification for RootDoc.classes() and PackageDoc.allClasses() (4748238, stddoclet)