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

[Nir Lisker]

On Sun, 6 Aug 2023 09:16: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:
> 
>   Improve Subscription javadoc

modules/javafx.base/src/main/java/javafx/util/Subscription.java line 33:

> 31: /**
> 32:  * A {@code Subscription} represents the encapsulation of the result of an action
> 33:  * that can be cancelled. Subscriptions can be obtained, for example, as a result

The first sentence is a bit cryptic to me. I'm looking at `Runnable` that is basically a less fancy version of `Subscription` (in a way, `Subscription` could extend `Runnable`). Maybe something like
"Represents a cancel/cleanup operation for an action that can be cancelled/allocates resources".
You can also choose either.

I would also add a general example after the first paragraph, maybe like this:


class Person {

    public Subscription subscribeToNewspaper(Newspaper paper) {
        register(paper);
        return () -> unregister(paper);
    }

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

PR Review Comment: https://git.openjdk.org/jfx/pull/1177#discussion_r1285270811