Summary

Add javadoc command-line options to generate documentation for API changes in specific releases, including added and newly deprecated API elements.

Problem

It is sometimes difficult for developers to keep up with API changes in recent releases of the JDK. While information about new features is usually available in release notes, the API documentation generated by javadoc is often the first or even only piece of documentation consulted by developers.

While some information about the release in which an API change was introduced is available in the API documentation based on the javadoc @since tag and the java.lang.Deprecated annotation interface, there is currently no place in the documentation where this information is collected and can be viewed as a whole.

While this problem statement is focused on our own use of javadoc for documenting the Java platform libraries, we believe the same problem exists for other large and fast moving code bases.

Solution

The proposed solution is to introduce two new options to the javadoc tool:

• The --since option is used to specify one or more releases for which to document API changes. The information is documented in a new summary page.

• the --since-label option allows to provide a human-readable description for the release or releases specified by the --since option.

The documentation of API changes in the specified releases is based on the javadoc @since tag and the since() element of the java.lang.Deprecated annotation interface. Based on this information, javadoc creates a new "New API" summary page with API elements added in the specified releases, and enriches the "Deprecated API" page with information about elements that were first deprecated in the specified releases.

An alternative approach would be to present this information as a separate resource outside of the API documentation. Tags and annotations in the source code are not always correct, and more reliable information about API changes may exist in other places such as official specifications. However, this outside information is not easily available, and adding the information to a central piece of documentation makes it much more accessible than as a separate resource.

During the prototyping of this feature we experimented with different alternative ways of displaying this information, including the possibility to specify a "display name" for each specified release. After several rounds of experimentation we converged on the design described in this document.

Specification

The following options are added to the javadoc tool:

--since <release>(,<release>)*
    Document new and deprecated API in the specified releases

--since-label <text>
    Provide text to use in the heading of the "New API" page

API changes for the specified releases are documented based on exact string comparison with the values of javadoc @since tags and java.lang.Deprecated since() elements in the documented source code.

A "New API" page is generated if any documented element has a javadoc @since tag with the same value as a release specified with the --since option. If a specified release matches the java.lang.Deprecated.since() value of any documented element (and unless the -nodeprecatedlist option is specified), the "Deprecated API" list is enhanced with information for the given release and element.

Multiple releases can be specified by passing a comma-separated list to the --since option:

--since 15,16,17

This entails that the feature can't be used for projects using commas as part of their release names. We think this is unlikely to cause any real world problems as such release names are very uncommon.

The order of releases on the command line is assumed to be chronological and is preserved in the generated documentation.

If the --since-label option is defined, its value is used as heading in the the "New API" page. The following options generate a page for APIs added in release 17 with "New API in JDK 17" as page heading.

--since 17 --since-label "New API in JDK 17"

The options below generate a page for new APIs added in releases 15, 16, and 17 with "New API in recent releases" as page heading.

--since 15,16,17 --since-label "New API in recent releases"

If the --since-label option is not provided, a localized default text is used in the heading of the "New API" page.