RFR: JDK-8316972: Add javadoc support for restricted methods

[Jonathan Gibbons]

On Fri, 13 Oct 2023 16:21:48 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> Please review a change to add support for restricted methods to JavaDoc. The bulk of this patch was contributed by @mcimadamore. It adds a warning note to the summary and details of restricted methods and a superscript to links to restricted methods, similar to what we already do with elements belonging to preview APIs. I added a summary page to list all restricted methods as well as a test.
> 
> To see the wording of this feature in context, the relevant parts of generated documentation can be reviewed here:
> 
> - [Method summary](https://cr.openjdk.org/~hannesw/8316972/api.00/java.base/java/lang/foreign/AddressLayout.html#method-summary)
> - [Method details](https://cr.openjdk.org/~hannesw/8316972/api.00/java.base/java/lang/foreign/AddressLayout.html#withTargetLayout(java.lang.foreign.MemoryLayout))
> - [Restricted Methods list](https://cr.openjdk.org/~hannesw/8316972/api.00/restricted-list.html)
> - [Restricted Methods help section](https://cr.openjdk.org/~hannesw/8316972/api.00/help-doc.html#restricted)
> 
> Since the messages for deprecated, preview, and restricted elements all use the same CSS in our default stylesheet, I decided to combine them into a single CSS rule. It is still possible to define distinct styles for these features in user-provided stylesheets.

Generally OK.
* One minor copy-paste naming issue
* One suggestion for `Workarounds`
* I defer to Maurizio and Alex for the wording of the warning text.

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java line 2217:

> 2215:         if (utils.isRestrictedAPI(forWhat)) {
> 2216:             //in Java platform:
> 2217:             var previewDiv = HtmlTree.DIV(HtmlStyle.restrictedBlock);

should this be `restrictedDiv` ?

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/WorkArounds.java line 432:

> 430:     }
> 431: 
> 432:     public boolean isRestrictedAPI(Element el) {

It would be good to file a JBS issue, requesting that this info should be available using `java.lang.model` API, perhaps `util.Elements.isRestricted(ExecutableElement)`
and to document that JBS issue here.

Bottom line: ideally, the doclet should be a clean client of the Language Model API, and other public API. Workarounds are "bad" and indicative of something wrong or missing elsewhere.

-------------

Marked as reviewed by jjg (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/16188#pullrequestreview-1681059080
PR Review Comment: https://git.openjdk.org/jdk/pull/16188#discussion_r1361328983
PR Review Comment: https://git.openjdk.org/jdk/pull/16188#discussion_r1361337536