RFR: 8345836: stable annotation documentation is incomplete

[Dan Heidinga]

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

> 144:  * (or zero) value.  Code which cannot prove proper ordering of
> 145:  * initialization may use stable variables without performing the null
> 146:  * (or zero) test.  Code which omits the null (or zero) test should be

* (or zero) value.  Code which cannot prove proper ordering of
 * initialization may use stable variables without performing the null
 * (or zero) test.  Code which omits the null (or zero) test should be

Do we want to say "may use without null check" or is there a missing "should not" in that sentence?

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

PR Review Comment: https://git.openjdk.org/leyden/pull/26#discussion_r1878446302