RFR: JDK-8295236: Update JavaDoc in javafx.geometry.Point3D

[Douglas Held]

On Thu, 13 Oct 2022 15:49:58 GMT, Kevin Rushforth <kcr at openjdk.org> 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