On Thu, 13 Oct 2022 15:49:58 GMT, Kevin Rushforth <[email protected]> wrote:
>> modules/javafx.graphics/src/main/java/javafx/geometry/Point3D.java line 414:
>>
>>> 412: /**
>>> 413: * Determines whether or not two objects are equal. Two instances
>>> of {@code Point3D}
>>> 414: * are equal if the values of their x, y, and z properties are
>>> equal.
>>
>> I would even write "i.f.f" because it's bidirectional.
>>
>> Also, `x`, `y`, and `z` should be in `{@code}`.
>
> I think this one is OK either as "if" or "if and only if" (if you do change
> it, I recommend spelling it out, although "iff" with no punctuation, would be
> acceptable). I agree with the request to use code style.
I disagree with both suggestions.
1. I think the extra verbosity (while factually correct) adds nothing, for such
a straightforward concept as equality of points in 3 space.
2. x, y and z are private and are not exposed in the JavaDoc. Further, the
exposed methods getX() etc. that I **could** link to, are not actually what are
evaluated in the method body.
I'd propose alternately that we keep "x, y and z" but call them "coordinates"
and not "properties". This agrees with other parts of the JavaDoc such as the
constructor, and getX() etc. method documentation.
-------------
PR: https://git.openjdk.org/jfx/pull/913
