RFR: 8258777: SkinBase: add api to un-/register invalidation-/listChange listeners [v2]

[Jeanette Winzenburg]

On Wed, 24 Mar 2021 23:28:47 GMT, Nir Lisker <nlisker at openjdk.org> wrote:

>> Jeanette Winzenburg has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   fixed missing/incorrect @since tags in new api doc
>
> modules/javafx.controls/src/main/java/javafx/scene/control/SkinBase.java line 268:
> 
>> 266:      *
>> 267:      * @param observable The observable for which all listeners should be removed.
>> 268:      * @return A single chained {@link Consumer} consisting of all {@link Consumer consumers} registered through
> 
> 1. There's no need for a `@link` on a class that is in the arguments or return of the method since they are linked there anyway, and it is recommended to use `@link` only the first time the class appears.
> 
> 2. You might want to clarify that by "chained" you mean that they were composed using `Consumer#andThen`, either using `@plainlink` on "chained", or explicitly by "chained using Consumer#andThen`. Then again, it might be obvious.

- kept only the link to the registerXX method (to clarify the scope of the removal)
- replaced "chained" by "composed" 
- concentrated on what that composed consumer does (performs all removed operations)

Not entirely certain whether it's clear enough now 

- should the description have an additional sentence `Returns a composed [same-as-in-returns]` Undecided.
- should the `same-as-in-returns` contain the specification of the sequence of performing (from the register method)? Tend to no (because it's getting too long), but then ..

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

PR: https://git.openjdk.java.net/jfx/pull/409