RFR: 8345836: stable annotation documentation is incomplete

[Roger Riggs]

On Mon, 9 Dec 2024 23:53:31 GMT, John R Rose <jrose at openjdk.org> wrote:

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

src/java.base/share/classes/jdk/internal/vm/annotation/Stable.java line 130:

> 128:  * any other context.  This implies that a constructor may choose to
> 129:  * initialize a stable variable, rather than "leaving it for later",
> 130:  * and that initial will be safely published, as if the field were

"initial" -> "initial value"

src/java.base/share/classes/jdk/internal/vm/annotation/Stable.java line 165:

> 163:  * <p>
> 164:  * After constant folding, the compiler can make use of may aspects of
> 165:  * the object: Its dynamic type, its length (if it is an array), and

"Its" -> "its". (no capital I needed)

src/java.base/share/classes/jdk/internal/vm/annotation/Stable.java line 215:

> 213:  * some other internal proof of correctness (accounting for any
> 214:  * possible racing API access), or by some appropriate disclaimer in
> 215:  * the API about undefined behavior.

This caution/warning might be better at the top of the file.

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

PR Review Comment: https://git.openjdk.org/leyden/pull/26#discussion_r1878235640
PR Review Comment: https://git.openjdk.org/leyden/pull/26#discussion_r1878240903
PR Review Comment: https://git.openjdk.org/leyden/pull/26#discussion_r1878249158