RFR: JDK-8286783: Expand use of @inheritDoc in InputStream and OutputStream subclasses

[Pavel Rappo]

On Sun, 15 May 2022 18:36:07 GMT, Joe Darcy <darcy at openjdk.org> wrote:

> Make the javadoc in the InputStream and OutputStream subclasses in core libs DRY-er by use of inheritDoc. (Any analagous changes to AudioInputStream in client libs will be done another a separate bug.) When the time comes, will do any necessary merging for the changes in[JDK-8286200.
> 
> Please also review the CSR to cover the introduction of implspec and implNote tags: https://bugs.openjdk.java.net/browse/JDK-8286784

1. One the one hand, it's not clear to me what criterion was used for adding `@Override` annotations. On the other hand, the more `@Override` annotations a codebase has, the better.
2. Have you compared the resulting documentation before and after the change? Aside from added `@implSpec` and `@implNote`, were there anything anything different?
3. I wonder if it makes sense to also reduce the size of the doc comments by changing explicit documentation inheritance for the `@param` and `@return` tags to implicit one, i.e. removing the tags on the overrider's side.

src/java.base/share/classes/java/io/SequenceInputStream.java line 217:

> 215:      * before the {@code close} method returns.
> 216:      *
> 217:      * @throws IOException {@inheritDoc}

Unexpected re-indentation; other similar cases do not have it.

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

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