RFR: 4756278: RFE: Insufficient API documentation for java.awt.Polygon constructor

[Phil Race]

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

> Appends: `, copying the array contents of {@code xpoints} and {@code ypoints}` to specify that the arrays in the constructor are explicitly copied.

Marked as reviewed by prr (Reviewer).

Really I'm not sure this is needed.
"Constructs and initializes a Polygon from the specified parameters."
Seems to be quite clear enough. It is "initialized" from these tells you right there that it won't be looking
back at this array afterwards - and there's no API that returns the array of points.

In fact I don't like the idea of saying that it "copying the array contents"
seems a bit too much like saying how the implementation must work. At least it doesn't say it copies
them into  internal arrays .. 

However .. I just noticed there are PROTECTED fields for these arrays. Grumble. Why ?
So someone stupid enough to sub-class Polygon can mess with even the copies.

So OK, let's add the new text but the reason we need it is because of questionable design.

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

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