Summary

Explain what may make the bounds field of a java.awt.Polygon null.

Problem

The current documentation is vague as to the reasoning for why it is null, only specifying: "This value can be null."

Solution

Replace the vague specification with more detail and clarify that the protected field should not be used by users.

Specification

@@ -101,11 +101,15 @@ */ public int[] ypoints;

 /**
  * The bounds of this {@code Polygon}.

- * 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}. * * @serial * @see #getBoundingBox() * @see #getBounds() * @since 1.0