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

[John Hendrikx]

On Sun, 6 Aug 2023 22:38:27 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> 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);
>     }

Thanks, that's a good suggestion.  I also thought the wording was a bit too hard to follow, but wanted to see what you thought.  I updated it to use your wording and added an example.

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

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