On Mon, 17 Oct 2022 17:07:40 GMT, Nir Lisker <nlis...@openjdk.org> wrote:
>> 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. Agreed, mentioning equality criteria sounds good to me too. How does this look ? /** * Indicates whether some other object is "equal to" this one. * Two instances of Point3D are equal if the return values of their * {@code getX}, {@code getY}, and {@code getZ} methods are equal. * * @param obj the reference object with which to compare * @return true if this Point3D is the same as the obj argument; false otherwise */ ------------- PR: https://git.openjdk.org/jfx/pull/913