RFR: JDK-8312058: Documentation improvements for subscription based listeners [v5]

[Kevin Rushforth]

On Fri, 11 Aug 2023 15:39:32 GMT, John Hendrikx <jhendrikx at openjdk.org> wrote:

>> Incorporates documentation review comments from #1069.
>> 
>> This PR should be kept minimal so it can be backported to JFX21; it should only contain documentation changes.
>
> John Hendrikx has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Fix sentence

Looks good. I made one suggestion for you to consider.

modules/javafx.base/src/main/java/javafx/beans/value/ObservableValue.java line 347:

> 345:      * subsequent values whenever its value changes. The {@code valueSubscriber} is called
> 346:      * for convenience since usually the user will want to initialize a value
> 347:      * and then update on changes.

Only the initial call is for convenience. Subsequent calls are necessary. Do you think it's worth calling this out? Something like:


     * ...The {@code valueSubscriber} is called immediately
     * for convenience, since usually the user will want to initialize a value
     * and then update on changes.


(I  might also add a comma before since, but that is more a matter of style)

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

Marked as reviewed by kcr (Lead).

PR Review: https://git.openjdk.org/jfx/pull/1177#pullrequestreview-1574028874
PR Review Comment: https://git.openjdk.org/jfx/pull/1177#discussion_r1291561301