On Tue, 14 Jan 2025 08:28:38 GMT, Chen Liang <li...@openjdk.org> wrote:
>> src/java.base/share/classes/java/util/zip/Deflater.java line 66:
>>
>>> 64: * {@code try}-with-resources statement. The {@linkplain
>>> Deflater#close() close() method} simply
>>> 65: * calls {@code end()}. Subclasses should override {@linkplain #end()}
>>> to clean up the
>>> 66: * resources acquired by the subclass.
>>
>> I wonder if the note for subclasses should move to the end method as
>> implSpec, it looks out of place in the class API note.
>
> I believe an `@implSpec` only restricts the implementation of this immediate
> method, such as those seen on default methods, and has no impact on the
> overrides. If we need to specify something for overrides to abide to, I
> believe they usually stay in the API specification itself.
> I wonder if the note for subclasses should move to the end method as
> implSpec, it looks out of place in the class API note.
Stuart, in his inputs here
https://github.com/openjdk/jdk/pull/19675#issuecomment-2172433871 and here
https://github.com/openjdk/jdk/pull/19675#discussion_r1848945718 had noted that
it would be useful to add this guidance to subclasses. But I see that he wasn't
fully convinced whether it must be a apiNote or something else. Given what you
note about moving this detail for subclasses to a `@implSpec` on the end()
method, I have now updated the PR accordingly.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/19675#discussion_r1914488626
