RFR: 8345836: stable annotation documentation is incomplete

[John R Rose]

The javadoc for jdk.internal.vm.annotation.Stable is incomplete.

The existing documentation gives an over-simple user model,
and does not explain how it is implemented.
Proposed new documentation will detail how the annotation
is implemented, and how it may be used correctly.

The improved documentation will makes it easier for JDK programmers
to use the annotation more aggressively, and more confidently.

This is a first cut.  Please comment…

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

Commit messages:
 - 8345836: stable annotation documentation is incomplete

Changes: https://git.openjdk.org/leyden/pull/26/files
  Webrev: https://webrevs.openjdk.org/?repo=leyden&pr=26&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8345836
  Stats: 172 lines in 1 file changed: 135 ins; 0 del; 37 mod
  Patch: https://git.openjdk.org/leyden/pull/26.diff
  Fetch: git fetch https://git.openjdk.org/leyden.git pull/26/head:pull/26

PR: https://git.openjdk.org/leyden/pull/26