On Fri, 13 Oct 2023 16:21:48 GMT, Hannes Wallnöfer <hann...@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
