On Wed, 24 Mar 2021 23:18:25 GMT, Nir Lisker <nlis...@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
