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

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

  incorporate all review comments

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

Changes:
  - all: https://git.openjdk.org/leyden/pull/26/files
  - new: https://git.openjdk.org/leyden/pull/26/files/ff94e0f5..273aa2e6

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

  Stats: 191 lines in 1 file changed: 107 ins; 23 del; 61 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