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

[Nir Lisker]

On Mon, 17 Oct 2022 15:24:48 GMT, Ambarish Rapte <arapte at openjdk.org> wrote:

>> ...correction, found in toString() as well.
>
> It would be suitable to align with our existing doc comment in other classes, for example as here,
> 
> 1. https://github.com/openjdk/jfx/blob/9768b5e42391e2d48aefffa3a3f6b1de6c30ef9d/modules/javafx.graphics/src/main/java/javafx/geometry/Point2D.java#L374
> 2. https://github.com/openjdk/jfx/blob/9768b5e42391e2d48aefffa3a3f6b1de6c30ef9d/modules/javafx.graphics/src/main/java/javafx/geometry/Insets.java#L103
> 3. https://github.com/openjdk/jfx/blob/9768b5e42391e2d48aefffa3a3f6b1de6c30ef9d/modules/javafx.graphics/src/main/java/javafx/geometry/BoundingBox.java#L169
> 
> 
> I would recommend to use as in Point2D,
> 
> 
>     /**
>      * Indicates whether some other object is "equal to" this one.
>      *
>      * @param obj the reference object with which to compare
>      * @return true if this Point3D is the same as the obj argument; false otherwise
>      */

I think that we should explain what makes 2 objects equal. Even if we don't explicitly name the methods used for comparison, we could say "2 points are equals if their coordinates are equal".

By the way, I have https://bugs.openjdk.org/browse/JDK-8226930 assigned to go over some dubious equals/hashcode implementations, in case you want to delegate the task.

-------------

PR: https://git.openjdk.org/jfx/pull/913