On Wed, 5 Jan 2022 10:51:28 GMT, John Hendrikx <[email protected]> wrote:
>> modules/javafx.base/src/main/java/javafx/beans/value/ObservableValue.java
>> line 152:
>>
>>> 150: * @return an {@link ObservableValue} which provides a mapping of
>>> the value
>>> 151: * held by this {@code ObservableValue}, and provides {@code
>>> null} when
>>> 152: * this {@code ObservableValue} holds {@code null}, never null
>>
>> No need for `@link`.
>>
>> Since we already explained how the mapping works, maybe we can be more brief
>> here:
>>
>> an {@code ObservableValue} that holds the result of the mapping of the value
>> held by this {@code ObservableValue}; never {@code null} itself
>
> I think that `@return` should mention that the returned observable can hold
> `null`, how about:
>
> an {@code ObservableValue} that holds a mapping of this {@code
> ObservableValue}'s value
> or holds {@code null} when the value is {@code null}; never returns
> {@code null}
Good idea to mention that it can hold `null`.
I slightly prefer to say that the returned `ObservableValue` holds the result
of the mapping rather than holds the mapping. I don't really mind it, but it's
the phrasing used in the method description "holds the result of applying a
mapping". "The mapping" itself could be mistaken for the mapping `Function` in
my opinion. If you think it's clear, you can change it to that phrasing, it's
also fine.
-------------
PR: https://git.openjdk.java.net/jfx/pull/675
