RFR: 8277300: Issues with javadoc support for preview features [v3]

[Jan Lahoda]

> 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

Jan Lahoda has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains six additional commits since the last revision:

 - Cleanup.
 - Merge branch 'master' into JDK-8277300
 - Merge branch 'master' into JDK-8277300
 - Cleanup
 - Cleanup
 - 8277300: Issues with javadoc support for preview features

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

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/6848/files
  - new: https://git.openjdk.java.net/jdk/pull/6848/files/5ed89c02..d4ea9829

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=6848&range=02
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=6848&range=01-02

  Stats: 51162 lines in 1709 files changed: 35048 ins; 8811 del; 7303 mod
  Patch: https://git.openjdk.java.net/jdk/pull/6848.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/6848/head:pull/6848

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