JDK-8287524 : Improve checkboxes to select releases on deprecated API page
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 19
  • Priority: P4
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2022-05-30
  • Updated: 2022-06-06
  • Resolved: 2022-06-06
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 19
19 masterFixed
Related Reports
Relates :  
JDK-8268422 - Find a better way to select releases in "New API" page
Description
In JDK-8268422 we replaced the table tabs in the "Deprecated API" and "New API" pages with rows of checkboxes to select visible elements by release. While this works well in the "New API" page which only contains elements for the listed releases, there are various conditions that lead to suboptimal results for the "Deprecated API" page:

 - Checkboxes are generated for all releases defined via `--since` option. This by itself is not ideal, because the the purpose of the `--since` option is to select contents of the "New API" page, and it seems arbitrary to also use the same release list for the "Deprecated API" page, which may have a very different set of `Deprecated.since` values. In the future it may therefore be a good idea to uncouple the selection of release checkboxes from the `--since` option. Since this is a non-trivial change and we are very close to feature freeze, as a short term fix I propose to only create checkboxes in the Deprecated API page for releases that are both defined via `--since` option and also occur in documented elements annotated with `java.lang.Deprecated`.

If there are values of `Deprecated.since` that are not contained in the list defined via `--since` option there is no way to control their visibility. This problem occurs in the JDK documentation[1] which contains a lot of elements deprecated before version 12. These elements are always visible, therefore diminishing the usefulness of the checkbox feature. The solution I propose (short of displaying checkboxes for all occurring release values, which creates a few new problems) is to add a checkbox labeled "others" or "other releases" to control releases not contained in the list if such releases exist in the documented code.

[1]: http://cr.openjdk.java.net/~hannesw/8268422/api.06/deprecated-list.html

- A checkbox is created if the release list only contains a single element. This is the only one of these issue that also applies to the "New API" page. If there is only one element in the release list no checkbox should be generated.
Comments
Changeset: 4d6fb515 Author: Hannes Wallnöfer <hannesw@openjdk.org> Date: 2022-06-06 11:11:43 +0000 URL: https://git.openjdk.java.net/jdk/commit/4d6fb515516dfc5f04c9d8e9c3602292e89df52a
06-06-2022
A pull request was submitted for review. URL: https://git.openjdk.java.net/jdk/pull/8973 Date: 2022-06-01 14:46:31 +0000
01-06-2022