RFR: 4668290: unclear spec for Polygon.bounds field

[Phil Race]

On Mon, 26 Sep 2022 02:27:53 GMT, SWinxy <duke at openjdk.org> wrote:

> New documentation replaces the `This value can be null.`:
> 
> When created, {@link #invalidate() invalidated}, or {@link #reset() reset},
> this becomes {@code null}. To get out of the null state,
> {@link #getBounds()} called with {@link #npoints} being greater than
> {@code 0} will transfer into a non-null {@link Rectangle}.
> 
> 
> I think I've got the reason for why it can be `null` correct, but you never know.
> 
> In javax.swing.text.html.Map, I've replaced setting the field to null with the equivalent #invalidate(). This may mean we can make the field private in the future.

src/java.desktop/share/classes/java/awt/Polygon.java line 111:

> 109:      * {@link #getBounds()} called with {@link #npoints} being greater than
> 110:      * {@code 0} will transfer into a non-null {@link Rectangle}.
> 111:      *

Another dubious piece of design. This should never have been exposed in the API.
What we need to say here is
/*
 * The value of this field is updated by the implementation which may set it to null and will
 *   re-evaluate it as needed. Application sub-classes should never access this field.
 */
And leave it at that.

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

PR: https://git.openjdk.org/jdk/pull/10417