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

[John Hendrikx]

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 now. Do you still prefer to repeat the behavior of the subscription in each of the new methods over the centralized one in [#1069 (comment)](https://github.com/openjdk/jfx/pull/1069#discussion_r1261873147)?

I'm really not quite sure where to put that.  I don't think it would go well with `Subscription` since it assumes observables, and things like `ObservableValue#when`.  We'd need to word it a lot more general then, and it would be hard to refer to `ObservableValue#when`, or general rules about garbage collection (I think that would depend on the method providing the subscriptions, which may not have such restrictions).

Reading `ObservableValue` documentation though, I think it could use some updating.  It mentions change and invalidation events, and their listeners, but nothing about the subscriptions as of yet.

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

PR Comment: https://git.openjdk.org/jfx/pull/1177#issuecomment-1675429487