RFR: 8277300: Issues with javadoc support for preview features

[Pavel Rappo]

On Wed, 15 Dec 2021 09:41:15 GMT, Jan Lahoda <jlahoda at openjdk.org> wrote:

> This is a patch that tweaks a bit the PREVIEW superscript which is marking preview APIs in javadoc. This is based on the experience with the Loom's fibers javadoc.
> 
> Namely, the changes are:
> 
>  * for methods inside a preview class:
>    * show the PREVIEW superscript, unless:
>    * the reference is inside the enclosing (preview) class, in which case skip the PREVIEW superscript
>    * ensure the PREVIEW superscript refers to the class' Preview note, not to the non-existing method's Preview note
> * for preview classes nested inside preview classes, ensure these are considered preview by themselves, not only as referring to a preview class
> * avoid the PREVIEW superscript inside code snippets.
> 
> A sample javadoc with these changes is here:
> http://cr.openjdk.java.net/~jlahoda/8277300/fibers-docs.00/api/java.base/java/util/concurrent/StructuredExecutor.html
> http://cr.openjdk.java.net/~jlahoda/8277300/fibers-docs.00/api/java.base/java/util/concurrent/StructuredExecutor.CompletionHandler.html

Changes to the snippet portion of this PR look good.

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

Marked as reviewed by prappo (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/6848