BufferedImage documentation inconsistent with implementation

[Philip Race]

I submitted https://bugs.openjdk.org/browse/JDK-8306320

The PR should use that bug ID and the summary fom the bug.
We will need a CSR.

-phil.

On 4/12/23 3:08 AM, Martin Desruisseaux wrote:
>
> Hello all
>
> BufferedImage implements WritableRenderedImage, but the javadoc of all 
> WritableRenderedImage methods are inconsistent with implementation:
>
>   * getWritableTile(…) said "All registered TileObservers are notified
>     when a tile goes from having no writers to having one writer" but
>     the implementation doesn't do that.
>   * releaseWritableTile(…) said "All registered TileObservers are
>     notified when a tile goes from having one writer to having no
>     writers" but the implementation does nothing.
>   * isTileWritable(…) said "throws ArrayIndexOutOfBoundsException if
>     both tileX and tileY are not equal to 0" but the implementation
>     throws IllegalArgumentException is *either* tileX or tileY is not 0.
>   * addTileObserver(…) and removeTileObserver(…) are no-op, but the
>     javadoc don't said that.
>
> Should the javadoc be updated for saying that most methods are 
> actually no-op, or should the implementation be updated with real 
> support of listeners? Or should BufferedImage be considered as 
> permanently checkout out for writing, in which case the current 
> javadoc is not wrong (except above-cited throws clause) but a note 
> about the "permanently checkout-out" behavior would be helpfui?
>
>     Martin
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/client-libs-dev/attachments/20230418/77fb029c/attachment.htm>