RFR: 8345836: stable annotation documentation is incomplete [v6]

[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…

John R Rose has updated the pull request incrementally with one additional commit since the last revision:

  remove stray word

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

Changes:
  - all: https://git.openjdk.org/leyden/pull/26/files
  - new: https://git.openjdk.org/leyden/pull/26/files/5070a26b..aa18de77

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=leyden&pr=26&range=05
 - incr: https://webrevs.openjdk.org/?repo=leyden&pr=26&range=04-05

  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 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