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

[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 refreshed the contents of this pull request, and previous commits have been removed. The incremental views will show differences compared to the previous content of the PR. The pull request contains one new commit since the last revision:

  more edits, better examples, section headings

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

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

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

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