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

[Jeanette Winzenburg]

On Wed, 24 Mar 2021 23:18:25 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 250:
> 
>> 248:      *
>> 249:      * @param observable the observable to observe for invalidation events
>> 250:      * @param consumer the consumer
> 
> Could be just me because I'm unfamiliar with this API, but I'd like to see an explanation for what the consumer is used for. If the consumer is executed on invalidation events on this observable, then clearly state it. Maybe the doc could be something like:
> 
>     Registers an action to take when an {@code Observable} is invalidated. 
>     An {@code InvalidationListener} is registered on the given {@code observable} and the {@code consumer} is run 
>     whenever the listener sends an invalidation event. If multiple consumers are registered on the same observable, 
>     they are run in the order in which they were registered.
> 
>     @param observable the observable to observe for invalidation events
>     @param consumer the action to take when the observable is invalidated
> 
> Since it's a `protected final` method, I don't think that the "Subclasses can use this..." portion is necessary - that's the only use of these methods.

Changed the api doc along your suggestions (for invalidationListener related methods only - those for the other types of listener will be changed analogously once the wording is agreed on :)

did deviate a bit from your suggestion in

- instead of _action to take_ I used _operation to perform_ because in ui contexts, _action_ feels a bit loaded and the replacement is from the doc of Consumer in its overview and method doc for accept
- removed mentioning of InvalidationListener: while we do have it, the when/how/how many are added is an implementation detail 

Also clarified the null handling: both parameters can be null, if so nothing happens.

Still not quite clear, when to use code tags in the description (vs. plain words) - [styling doc](https://www.oracle.com/de/technical-resources/articles/java/javadoc-tool.html) seems to advocate it for all class names, actual java doc (including javafx doc) seems to use it inconsistently.

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

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