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

[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 Alex comments

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

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

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

  Stats: 35 lines in 1 file changed: 12 ins; 10 del; 13 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