JDK-8316972 : Add javadoc support for restricted methods
  • Type: Enhancement
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 22
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2023-09-26
  • Updated: 2023-10-24
  • Resolved: 2023-10-17
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 22
22 b20Fixed
Related Reports
Blocks :  
JDK-8316970 - Add internal annotation to mark restricted methods
Relates :  
JDK-8312522 - Implementation of Foreign Function & Memory API
Relates :  
JDK-8318601 - Remove javadoc text about restricted methods
Description
Javadoc should support restricted methods in the Java SE API. The support should be similar to what we do for preview methods that is:

* In the "method summary" section, restricted methods should be clearly visible.
* When clicking on a method details, a "bubble" containing more info about what restricted methods are should be shown.
* Links to restricted methods should be rendered with the classic superscript notation which is used for preview API methods.

An example of javadoc output can be found here:
https://cr.openjdk.org/~mcimadamore/jdk/restricted_javadoc/javadoc/java.base/java/lang/foreign/Linker.html#method-summary

The patch to generate that javadoc is available here:
https://github.com/openjdk/jdk/compare/master...mcimadamore:jdk:restricted_anno?expand=1
Comments
Changeset: 0ba48ef4 Author: Hannes Wallnöfer <hannesw@openjdk.org> Date: 2023-10-17 20:32:41 +0000 URL: https://git.openjdk.org/jdk/commit/0ba48ef4ab7b80c21bb9484ba0a15c5742ba76cf
17-10-2023
A pull request was submitted for review. URL: https://git.openjdk.org/jdk/pull/16188 Date: 2023-10-13 16:21:48 +0000
13-10-2023
Maybe create a "Restricted Methods" summary page, similar to the "Preview Methods" summary page, but then maybe just link that page from the static and dynamic index pages, but not from the main navbar.
27-09-2023
Recommended text for the "bubble" shown in the details of method M: M is a restricted method of the Java platform. Programs can only use M when access to restricted methods is enabled. Restricted methods are unsafe and, if used incorrectly, might crash the Java runtime or corrupt memory.
26-09-2023