RFR: 6185110: Undefined behaviour of SampleModel for width, height < 0

[Phil Race]

On Fri, 10 Oct 2025 22:30:53 GMT, Phil Race <prr at openjdk.org> wrote:

> The only significant change here is to ensure that all SampleModel types throw a specified exception if a client
> calls any of the following methods with a negative width or height.
> getPixels(..)
> setPixels(..)
> getSamples(..)
> setSamples(..)
> 
> The rest is fixing the javadoc to properly describe what happens and some minor cleanup.
> I use {@inheritDoc} to avoid repeating the super-class doc. And no one now has to tediously compare them.
> I could just delete the javadoc but that would cause no javadoc to be generated for an overridden method.
> There were a couple of surprises with {@inheritDoc} and the one I had to deal with is that declared RuntimeExceptions
> are not inherited. You need to explicitly re-add them. This because if it isn't an exception in the method signature (as in  foo() throws BarException), and instead you only have "@throws BarException" it will not be inherited.
> 
> I added a test which verifies the behaviour for illegal arguments.
> 
> CSR is here https://bugs.openjdk.org/browse/JDK-8369623

> > That would not help. In fact it makes it harder.
> 
> I tried building this method without any additional Javadoc, using only @OverRide to highlight that it overrides the parent method. The generated Javadoc for ComponentSampleModel does not include a separate description of getPixel, but instead provides a link to the inherited method in the parent class, which contains all the relevant information. Isn’t this exactly the behavior we want to achieve?

The problem with that, as I wrote somewhere, perhaps not here, is that it looks to the reader of the source as if there is no javadoc for this method. {@inheritDoc} gives you the confidence that someone has thought about javadoc !
That is why it did not seem like an acceptable way to proceed.
But it is an interesting thing that in that case javadoc apparently feels it is OK to include the exceptions which it thinks are inappropriate if you ask to inherit the doc ...

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

PR Comment: https://git.openjdk.org/jdk/pull/27754#issuecomment-3444934443