RFR: JDK-8286604: Update InputStream and OutputStream to use @implSpec

[Joe Darcy]

On Thu, 12 May 2022 12:24:17 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> While doing a CSR review of another issue, I noticed some cases in InputStream and OutputStream what would benefit from being upgraded to implSpec and related javadoc tags.
>> 
>> The "A subclass must provide an implementation of this method." statements on several abstract methods don't add much value, but I chose to leave them in for this request.
>> 
>> Please also review the corresponding CSR: https://bugs.openjdk.java.net/browse/JDK-8286605
>
> src/java.base/share/classes/java/io/InputStream.java line 177:
> 
>> 175:      *
>> 176:      * @apiNote
>> 177:      * A subclass must provide an implementation of this method.
> 
> Is this sentence useful to keep? The method is abstract so a concrete implementation has to implement it. On the other other hand, an abstract subclass does not need to implement it.

If such a sentence occurred in new code, I would recommend it be removed. I left it in place in the spirit of just adding apiNote, implSpec, etc., but I'm happy to delete these comments too. I assume it was deemed useful to readers of JDK 1.0, but the assumed background of Java developers now is rather different :-)

> src/java.base/share/classes/java/io/InputStream.java line 688:
> 
>> 686:      * @implSpec
>> 687:      * The {@code mark} method of {@code InputStream} does
>> 688:      * nothing.
> 
> Minor nit but the line break can be removed so that "nothing" is on the same line.

Sure. (I default to not making such reflow changes in the initial version of a patch to avoid spurious diffs.

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

PR: https://git.openjdk.java.net/jdk/pull/8663