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

[Alex Buckley]

First paragraph:

Both "initial default value" and "default initial value" appear, and I 
originally planned to just regularize the order of adjectives. But then 
I questioned whether "initial" adds value fast enough. The edits below, 
which involve dropping and replacing individual words, produce a 
smoother story IMO.

"its initial default (null or zero) value"
   ->
"its default value (null or zero)"

"When the first value is stored into the field (assuming it is not a 
duplicate of the the field's default initial value), the VM may ..."
   ->
"When the first value is stored into the field that is not the field's 
default value, the VM may ..."

"Or is the user waiting until later to assign another value to the 
variable?"
   ->
"Or is the user waiting until later to assign a permanent value to the 
variable?"

"The VM does not systematically record stores of a default null (or 
primitive zero), so there is no way for the VM to decide if a default 
field value is an undisturbed initial default value"
   ->
"The VM does not systematically record stores of a null (resp., zero) to 
a stable variable, so there is no way for the VM to decide if a field's 
current value is its undisturbed default value or has been overwritten 
with an intentionally stored null (resp., zero)."


In the Example section:

- The phrase "stable value" has crept in.

- Is a _value_ constant-foldable? Or a _variable_? I think the latter. 
However, "constant-foldable string" appears more than once, suggesting 
the former. There are numerous other clauses in the text which muddy the 
issue -- I suggest taking a fine tooth comb over the text.

- The "As a very simple example ..." paragraph is weird, coming after so 
many other examples. I think the best thing is to turn it into code.

- The final paragraph about "mutually exclusive" and "never be part of 
public APIs" gives substantive advice about using stable variables that 
should not be buried in an examples section. I recommend moving this 
paragraph up to "Stable Variable Life Cycle" as a first step.

Alex

On 12/12/2024 1:03 AM, John R Rose wrote:
> On Thu, 12 Dec 2024 08:13: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…
>>
>> 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
> 
> For easier review, here is a rendered version of the most recent changes.
> It is a stand-alone HTML, so you won't get the nice style-sheet.
> 
> https://cr.openjdk.org/~jrose/jvm/Stable.html
> 
> -------------
> 
> PR Comment: https://git.openjdk.org/leyden/pull/26#issuecomment-2538260936