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][javadoc-since] and the
[since() element][deprecated-since]
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.

[javadoc-since]: https://docs.oracle.com/en/java/javase/16/docs/specs/javadoc/doc-comment-spec.html#since
[deprecated-since]: https://docs.oracle.com/en/java/javase/16/docs/api/java.base/java/lang/Deprecated.html#since()

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.