RFR: 8277300: Issues with javadoc support for preview features

[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

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

Commit messages:
 - Cleanup
 - Cleanup
 - 8277300: Issues with javadoc support for preview features

Changes: https://git.openjdk.java.net/jdk/pull/6848/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=6848&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8277300
  Stats: 243 lines in 8 files changed: 217 ins; 8 del; 18 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