On Fri, 10 Oct 2025 22:30:53 GMT, Phil Race <[email protected]> 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
