Summary

Update InputStream and OutputStream to use implSpec and related tags.

Problem

Specification requirements of specific methods are included in general javadoc for the method rather than implementation requirements.

Solution

Update the javadoc to use the relevant tags.

Specification

diff --git a/src/java.base/share/classes/java/io/InputStream.java b/src/java.base/share/classes/java/io/InputStream.java
index 43faad69d1a..97e76b27878 100644
--- a/src/java.base/share/classes/java/io/InputStream.java
+++ b/src/java.base/share/classes/java/io/InputStream.java
@@ -173,8 +173,6 @@ public abstract class InputStream implements Closeable {
      * blocks until input data is available, the end of the stream is detected,
      * or an exception is thrown.
      *
-     * <p> A subclass must provide an implementation of this method.
-     *
      * @return     the next byte of data, or {@code -1} if the end of the
      *             stream is reached.
      * @throws     IOException  if an I/O error occurs.
@@ -201,7 +199,8 @@ public abstract class InputStream implements Closeable {
      * leaving elements {@code b[}<i>k</i>{@code ]} through
      * {@code b[b.length-1]} unaffected.
      *
-     * <p> The {@code read(b)} method for class {@code InputStream}
+     * @implSpec
+     * The {@code read(b)} method for class {@code InputStream}
      * has the same effect as: <pre>{@code  read(b, 0, b.length) }</pre>
      *
      * @param      b   the buffer into which the data is read.
@@ -245,7 +244,8 @@ public abstract class InputStream implements Closeable {
      * {@code b[off-1]} and elements {@code b[off+len]} through
      * {@code b[b.length-1]} are unaffected.
      *
-     * <p> The {@code read(b, off, len)} method
+     * @implSpec
+     * The {@code read(b, off, len)} method
      * for class {@code InputStream} simply calls the method
      * {@code read()} repeatedly. If the first such call results in an
      * {@code IOException}, that exception is returned from the call to
@@ -522,7 +522,8 @@ public abstract class InputStream implements Closeable {
      * returns 0, and no bytes are skipped. Subclasses may handle the negative
      * value differently.
      *
-     * <p> The {@code skip} method implementation of this class creates a
+     * @implSpec
+     * The {@code skip} method implementation of this class creates a
      * byte array and then repeatedly reads into it until {@code n} bytes
      * have been read or the end of the stream has been reached. Subclasses are
      * encouraged to provide a more efficient implementation of this method.
@@ -632,10 +633,12 @@ public abstract class InputStream implements Closeable {
      * {@link IOException} if this input stream has been closed by invoking the
      * {@link #close()} method.
      *
-     * <p> The {@code available} method of {@code InputStream} always returns
+     * @implSpec
+     * The {@code available} method of {@code InputStream} always returns
      * {@code 0}.
      *
-     * <p> This method should be overridden by subclasses.
+     * @apiNote
+     * This method should be overridden by subclasses.
      *
      * @return     an estimate of the number of bytes that can be read (or
      *             skipped over) from this input stream without blocking or
@@ -650,7 +653,8 @@ public abstract class InputStream implements Closeable {
      * Closes this input stream and releases any system resources associated
      * with the stream.
      *
-     * <p> The {@code close} method of {@code InputStream} does
+     * @implSpec
+     * The {@code close} method of {@code InputStream} does
      * nothing.
      *
      * @throws     IOException  if an I/O error occurs.
@@ -676,8 +680,8 @@ public abstract class InputStream implements Closeable {
      *
      * <p> Marking a closed stream should not have any effect on the stream.
      *
-     * <p> The {@code mark} method of {@code InputStream} does
-     * nothing.
+     * @implSpec
+     * The {@code mark} method of {@code InputStream} does nothing.
      *
      * @param   readlimit   the maximum limit of bytes that can be read before
      *                      the mark position becomes invalid.
@@ -721,7 +725,8 @@ public abstract class InputStream implements Closeable {
      *     to subsequent callers of the {@code read} method depend on the
      *     particular type of the input stream. </ul></ul>
      *
-     * <p>The method {@code reset} for class {@code InputStream}
+     * @implSpec
+     * The method {@code reset} for class {@code InputStream}
      * does nothing except throw an {@code IOException}.
      *
      * @throws  IOException  if this stream has not been marked or if the
diff --git a/src/java.base/share/classes/java/io/OutputStream.java b/src/java.base/share/classes/java/io/OutputStream.java
index 124a3e7365b..3b3fb30b890 100644
--- a/src/java.base/share/classes/java/io/OutputStream.java
+++ b/src/java.base/share/classes/java/io/OutputStream.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1994, 2022, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -102,9 +102,6 @@ public abstract class OutputStream implements Closeable, Flushable {
      * to the output stream. The byte to be written is the eight
      * low-order bits of the argument {@code b}. The 24
      * high-order bits of {@code b} are ignored.
-     * <p>
-     * Subclasses of {@code OutputStream} must provide an
-     * implementation for this method.
      *
      * @param      b   the {@code byte}.
      * @throws     IOException  if an I/O error occurs. In particular,
@@ -135,11 +132,7 @@ public abstract class OutputStream implements Closeable, Flushable {
      * output stream in order; element {@code b[off]} is the first
      * byte written and {@code b[off+len-1]} is the last byte written
      * by this operation.
-     * <p>
-     * The {@code write} method of {@code OutputStream} calls
-     * the write method of one argument on each of the bytes to be
-     * written out. Subclasses are encouraged to override this method and
-     * provide a more efficient implementation.
+     *
      * <p>
      * If {@code b} is {@code null}, a
      * {@code NullPointerException} is thrown.
@@ -148,6 +141,15 @@ public abstract class OutputStream implements Closeable, Flushable {
      * {@code off+len} is greater than the length of the array
      * {@code b}, then an {@code IndexOutOfBoundsException} is thrown.
      *
+     * @implSpec
+     * The {@code write} method of {@code OutputStream} calls
+     * the write method of one argument on each of the bytes to be
+     * written out.
+     *
+     * @apiNote
+     * Subclasses are encouraged to override this method and
+     * provide a more efficient implementation.
+     *
      * @param      b     the data.
      * @param      off   the start offset in the data.
      * @param      len   the number of bytes to write.
@@ -176,7 +178,8 @@ public abstract class OutputStream implements Closeable, Flushable {
      * stream guarantees only that bytes previously written to the stream are
      * passed to the operating system for writing; it does not guarantee that
      * they are actually written to a physical device such as a disk drive.
-     * <p>
+     *
+     * @implSpec
      * The {@code flush} method of {@code OutputStream} does nothing.
      *
      * @throws     IOException  if an I/O error occurs.
@@ -189,7 +192,8 @@ public abstract class OutputStream implements Closeable, Flushable {
      * associated with this stream. The general contract of {@code close}
      * is that it closes the output stream. A closed stream cannot perform
      * output operations and cannot be reopened.
-     * <p>
+     *
+     * @implSpec
      * The {@code close} method of {@code OutputStream} does nothing.
      *
      * @throws     IOException  if an I/O error occurs.