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

[Nir Lisker]

On Mon, 31 Jul 2023 11:51:24 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 with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains three additional commits since the last revision:
> 
>  - Use @implSpec tag
>  - Merge branch 'master' of https://git.openjdk.org/jfx into feature/subscriptions-doc-improvements
>  - Documentation improvements

I think that the documentation on `Subscription` still needs to be improved beyond a single sentence. It should include how to use the interface and give use cases. I'll need to think about a good first paragraph. For the use cases, maybe the ones you outlines in https://github.com/openjdk/jfx/pull/1069/files#r1263857263. I also think that a short review of the methods it offers is useful:

Subscriptions can also be combined using {@link #combine} and {@link #and}, which allows for
multiple subscriptions to be unsubscribed together. This is useful when they share the same
lifecycle, for example, when performing cleanup for the same object.


Then there is the question of what to do with regards to its use in JavaFX. The previous description I gave in https://github.com/openjdk/jfx/pull/1069#discussion_r1261873147 is centered around `Observable/ObservableValue`. I think that it's still better to include this description somewhere rather than repeat a part of it in every method. Maybe it fits better in `Observable/ObservableValue`.

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

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