8275013: Improve discussion of serialization method declarations in java.io.Object{Input, Output}Stream

Reviewed-by: smarks, rriggs

src/java.base/share/classes/java/io/ObjectInputStream.java

@@ -145,8 +145,8 @@ import sun.security.action.GetIntegerAction;
  * entire graphs.
  *
  * <p>Serializable classes that require special handling during the
- * serialization and deserialization process should implement the following
- * methods:
+ * serialization and deserialization process should implement methods
+ * with the following signatures:
  *
  * <pre>
  * private void writeObject(java.io.ObjectOutputStream stream)
@@ -157,6 +157,12 @@ import sun.security.action.GetIntegerAction;
  *     throws ObjectStreamException;
  * </pre>
  *
+ * <p>The method name, modifiers, return type, and number and type of
+ * parameters must match exactly for the method to be used by
+ * serialization or deserialization. The methods should only be
+ * declared to throw checked exceptions consistent with these
+ * signatures.
+ *
  * <p>The readObject method is responsible for reading and restoring the state
  * of the object for its particular class using data written to the stream by
  * the corresponding writeObject method.  The method does not need to concern

src/java.base/share/classes/java/io/ObjectOutputStream.java

@@ -83,9 +83,10 @@ import sun.reflect.misc.ReflectUtil;
  *      oos.close();
  * </pre>
  *
- * <p>Classes that require special handling during the serialization and
- * deserialization process must implement special methods with these exact
- * signatures:
+ * <p>Serializable classes that require special handling during the
+ * serialization and deserialization process should implement methods
+ * with the following signatures:
+ *
  * <br>
  * <pre>
  * private void readObject(java.io.ObjectInputStream stream)
@@ -96,6 +97,12 @@ import sun.reflect.misc.ReflectUtil;
  *     throws ObjectStreamException;
  * </pre>
  *
+ * <p>The method name, modifiers, return type, and number and type of
+ * parameters must match exactly for the method to be used by
+ * serialization or deserialization. The methods should only be
+ * declared to throw checked exceptions consistent with these
+ * signatures.
+ *
  * <p>The writeObject method is responsible for writing the state of the object
  * for its particular class so that the corresponding readObject method can
  * restore it.  The method does not need to concern itself with the state