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.