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

[John Hendrikx]

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 [#1069 (comment)](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`.

I took a stab at creating a good first paragraph, and used your suggestion as the second paragraph. What do you think?

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

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