On Sun, 20 Mar 2022 03:08:59 GMT, Nir Lisker <nlis...@openjdk.org> wrote:
>> Both seem fine, I don't have any preference over one or the other. > > I struggled with finding a good description here > [previously](https://github.com/openjdk/jfx/pull/675#discussion_r777801130). > I think that mstr2 gave a good approach. What we can do if we want to have > "the best of both worlds" is to write something in this form: > > <Simple slightly-inaccurate summary>. More precisely, <Correct and more > convoluted description> > > > I would offer something like this based on your suggestions: > > > Creates a new {@code ObservableValue} that holds the value of a nested {@code > ObservableValue} supplied by the > given mapping function. The result is updated when either this or the nested > {@code ObservableValue} changes. > If either this or the nested value is {@code null}, the resulting value is > {@code null} (no mapping is applied if > this value is {@code null}). > More precisely, the created {@code ObservableValue} holds the value of an > {@code ObservableValue} resulting > from applying a mapping on this {@code ObservableValue}'s value. > > I'm honestly not sure the "More precisely" part is even needed at his point. > Up to you. > > The `@return` description can be changed accordingly with the simplified > explanation if you think it's clearer. > > You can also specify a `@throws` NPE if the mapping function parameter is > `null` instead of writing "cannot be null", like mstr2 suggested in another > place if you like this pattern. > > By the way, if we change "Creates an..." to "Creates a new..." we should > change it in the other methods. I don't think there's a difference. Resolving this one as we have this discussion elsewhere as well. ------------- PR: https://git.openjdk.java.net/jfx/pull/675
