Enhancements in Javadoc, Java SE 5.0

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
• Incompatibilities with Custom Doclets
• New Features and Bug Fixes
  • Command Line Options
  • Tags and Taglets
  • Links
  • Generated API Specifications
  • Formatting and Invalid HTML
  • Navigation Bar
  • Accessibility
  • Running Javadoc
  • Error/Warning/Status Messages
  • Doclet API

Notable New Features

• Generics, enums, and varargs: Added support for these new language features in the javadoc tool front-end (Doclet API) (4421066, tool) and standard doclet (4789689, stddoclet, 1 vote)
• Annotations: Added support for annotations and annotation types in the javadoc tool front-end (Doclet API) (4904495, tool) and standard doclet (4905985, stddoclet)
• BreakIterator: We have removed the -breakiterator warning messages from 5.0, and have left the default sentence-break algorithm unchanged from earlier releases. That is, the -breakiterator option is not the default in 5.0, nor do we expect it to become the default. This is a reversal from our former intention that the default would change in the "next major release" (5.0). This means if you have not modified your source code to eliminate the breakiterator warnings in 1.4.x, then you don't have to do anything, and the warnings will go away in 5.0. The reason for this reversal is because any benefit to having -breakiterator become the default would be outweighed by the incompatible source change it would require. We regret any extra work and confusion this has caused. (The -breakiterator option was added in 1.4.0; for English locale only, it forces the use of BreakIterator class to determine where the first sentence in a doc comment ends, as BreakIterator already does for other languages.) (4959985, tool)
  Furthermore, in a future release (hopefully 5.1) we will add new javadoc tags (feature request 4921374) to enable you to mark summaries explicitly and avoid using heuristics of any kind.
• New tags {@literal} and {@code} 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.
  The {@code} tag formats literal text in the code font; {@code abc} is equivalent to <code>{@literal abc}</code>.
• Tag {@value arg}: This inline tag now accepts the name of a program element: {@value package.class#field}. This enables it to be used in any doc comment, not just in the doc comment of the constant field. (4764045, stddoclet, 2 votes)
• package-info.java: You can now create a source file with this name to store package comments and annotations. It can be used in place of package.html (which supports only comments, not annotations). If package-info.java is present, javadoc should ignore package.html and look instead for the package doc comment immediately preceding the (possibly annotated) package declaration. The javadoc tool handles the selection and parsing of package-info.java and package.html and passes the doc comments to the doclet. See Package Comment Files.
• @Deprecated annotation: This is a new annotation in 5.0 that should be used in addition to the @deprecated tag for deprecating program elements. The Java Language Specification now requires compilers to issue warnings when the @Deprecated annotation (but not necessarily the tag) is used. The @deprecated tag provides a place to describe what replaces the deprecated program element. See @Deprecated annotation.
• Standard doclet reimplementation - The standard doclet and MIF doclet were re-implemented to share as much code as possible. This has made it possible to reduce the number of bugs in both doclets and raise the capabilities of the MIF doclet to that of the standard doclet. (The new MIF doclet has not yet been released -- it will probably be named version 1.4 Beta 1.) The key reason we merged these two doclets is because they both try to generate essentially the same document but in different formats (HTML and PDF). (4638723, stddoclet, 2 votes)
  We plan to publish this shared code as a doclet toolkit, as described on the Javadoc Tool home page.

  All new features are listed below.

Notable Bug Fixes

• Option -tag: (regression) Fixed -tag so its name can once again contain a dash "-", as it allowed in 1.4.1. (4920381, stddoclet, 59 votes)
• Hang due to {@inheritDoc}: No longer hangs when {@inheritDoc} (1) cannot inherit or (2) inherits from super-superinterface. (4812240, stddoclet, 18 votes)
• Tag @param: (regression) Fixed @param so the parameter name (the first argument) is printed even if incorrect, as it worked in 1.3.1. (4802275, stddoclet, 1 vote)
• Tag {@value}: Using {@value} in a custom tag no longer generates a NullPointerException. (4821796, stddoclet, 1 vote)
• Browser scroll bar: Internet Explorer no longer displays an unnecessary horizontal scroll bar when frames are showing. (4852280, stddoclet, 5 votes)
• Inheriting package-private docs: When -private option is used, now properly documents methods inherited from package-private classes only in the inherited method summary table and not in the detail section. (4780441, stddoclet, 5 votes)
• First sentence ending with {@inheritDoc}: The end of a first sentence containing {@inheritDoc} is now determined correctly. (4767038, stddoclet, 4 votes)
• First sentence broken link with {@docRoot}: A first sentence containing a {@docRoot} link is no longer broken in the single-page index. (4760191, stddoclet, 3 votes)
• Inherited comment link: An inherited comment now links directly to the proper member, not just to the class. (4368820, stddoclet, 1 vote)
• Alphabetic index sorting: Index sorting is again case-independent. Only in 1.4.1 and 1.4.2 it was sorted uppercase then lowercase. (4984419, stddoclet, no votes)

  All bug fixes are listed below.

Known Bugs

Javadoc 5.0 has no known bugs that cause it to hang or crash. You can view listings from our Bug Database. 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

• Bug fix: An inherited comment now links directly to the proper member, not just to the class. (4368820, stddoclet)
• Bug fix: The summary heading is no longer missing when a class has no direct members but inherits members. (4904036, stddoclet)
• Bug fix: Relative link in <a href> in first sentence no longer generates a broken link when it appears on other pages. (4460354, stddoclet)

  For more link bug fixes, see "Tags and Taglets", associated with the {@docRoot} tag.

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

  . (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)