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

[Alex Buckley]

Re: "A stable variable may be assigned its final value inside a class or 
object initializer" -- better to avoid "final value" since "final" is a 
property of variables -- prefer "permanent value" (as used elsewhere).

"For example, declaring two stable fields of type {@code int} and {@code 
String} creates a pair of stable variables" -- here, the field 
declarations are "syntax" while the creation of stable variables is 
"semantics" ... as such, the declarations should lean on the syntactic 
device `@Stable` rather than the semantic concept of "stable field". 
Recommend: "For example, suppose a class has two non-final fields of 
type int and String. Annotating the field declarations with @Stable 
creates a pair of stable variables. The fields are initialized to zero 
and null, respectively, in the usual way, but storing a non-zero integer 
in the first field or a non-null reference in the second field will 
enable the VM to expect ..."

Before "As an extended behavior," please insert a heading "Array-typed 
stable variables".

Before "As very simple example", please insert a heading "Constant 
folding of stable variables".

Before "Fields which are declared {@code final}", please insert a 
heading "`final` variables and stable variables".

Please consider adding further headings.

Alex

On 12/11/2024 1:36 PM, John R Rose 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…
> 
> John R Rose has updated the pull request incrementally with one additional commit since the last revision:
> 
>    incorporate all review comments
> 
> -------------
> 
> Changes:
>    - all: https://git.openjdk.org/leyden/pull/26/files
>    - new: https://git.openjdk.org/leyden/pull/26/files/ff94e0f5..273aa2e6
> 
> Webrevs:
>   - full: https://webrevs.openjdk.org/?repo=leyden&pr=26&range=01
>   - incr: https://webrevs.openjdk.org/?repo=leyden&pr=26&range=00-01
> 
>    Stats: 191 lines in 1 file changed: 107 ins; 23 del; 61 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