8037384: Fix wording in Javadoc of java.io.Serializable

8231547: Serializable class doc should link to serialization specification

Reviewed-by: rriggs, iris, chegar

Author: Stuart Marks

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

@@ -242,7 +242,8 @@
  * The record components are deserialized prior to the invocation of the record
  * constructor, hence this limitation (see
  * <a href="{@docRoot}/../specs/serialization/serial-arch.html#cyclic-references">
- * [Section 1.14, "Circular References"</a> for additional information).
+ * <cite>Java Object Serialization Specification,</cite>
+ * Section 1.14, "Circular References"</a> for additional information).
  * The process by which record objects are serialized or externalized cannot be
  * customized; any class-specific writeObject, readObject, readObjectNoData,
  * writeExternal, and readExternal methods defined by record classes are
@@ -262,7 +263,7 @@
  * @see java.io.ObjectOutputStream
  * @see java.io.Serializable
  * @see <a href="{@docRoot}/../specs/serialization/input.html">
- *     Object Serialization Specification, Section 3, Object Input Classes</a>
+ *      <cite>Java Object Serialization Specification,</cite> Section 3, "Object Input Classes"</a>
  * @since   1.1
  */
 public class ObjectInputStream

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

@@ -161,7 +161,7 @@
  * @see java.io.Serializable
  * @see java.io.Externalizable
  * @see <a href="{@docRoot}/../specs/serialization/output.html">
- *     Object Serialization Specification, Section 2, Object Output Classes</a>
+ *      <cite>Java Object Serialization Specification,</cite> Section 2, "Object Output Classes"</a>
  * @since       1.1
  */
 public class ObjectOutputStream

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

@@ -76,13 +76,13 @@
  *
  * <p>The algorithm to compute the SerialVersionUID is described in
  * <a href="{@docRoot}/../specs/serialization/class.html#stream-unique-identifiers">
- *     Object Serialization Specification, Section 4.6, Stream Unique Identifiers</a>.
+ *    <cite>Java Object Serialization Specification,</cite> Section 4.6, "Stream Unique Identifiers"</a>.
  *
  * @author      Mike Warres
  * @author      Roger Riggs
  * @see ObjectStreamField
  * @see <a href="{@docRoot}/../specs/serialization/class.html">
- *     Object Serialization Specification, Section 4, Class Descriptors</a>
+ *      <cite>Java Object Serialization Specification,</cite> Section 4, "Class Descriptors"</a>
  * @since   1.1
  */
 public class ObjectStreamClass implements Serializable {

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

@@ -43,20 +43,19 @@
  * serializable.  The serialization interface has no methods or fields
  * and serves only to identify the semantics of being serializable. <p>
  *
- * To allow subtypes of non-serializable classes to be serialized, the
- * subtype may assume responsibility for saving and restoring the
- * state of the supertype's public, protected, and (if accessible)
- * package fields.  The subtype may assume this responsibility only if
- * the class it extends has an accessible no-arg constructor to
- * initialize the class's state.  It is an error to declare a class
- * Serializable if this is not the case.  The error will be detected at
- * runtime. <p>
- *
- * During deserialization, the fields of non-serializable classes will
- * be initialized using the public or protected no-arg constructor of
- * the class.  A no-arg constructor must be accessible to the subclass
- * that is serializable.  The fields of serializable subclasses will
- * be restored from the stream. <p>
+ * It is possible for subtypes of non-serializable classes to be serialized
+ * and deserialized. During serialization, no data will be written for the
+ * fields of non-serializable superclasses. During deserialization, the fields of non-serializable
+ * superclasses will be initialized using the no-arg constructor of the first (bottommost)
+ * non-serializable superclass. This constructor must be accessible to the subclass that is being
+ * deserialized. It is an error to declare a class Serializable if this is not
+ * the case; the error will be detected at runtime. A serializable subtype may
+ * assume responsibility for saving and restoring the state of a non-serializable
+ * supertype's public, protected, and (if accessible) package-access fields. See
+ * the <a href="{@docRoot}/../specs/serialization/input.html#the-objectinputstream-class">
+ * <cite>Java Object Serialization Specification,</cite></a> section 3.1, for
+ * a detailed specification of the deserialization process, including handling of
+ * serializable and non-serializable classes. <p>
  *
  * When traversing a graph, an object may be encountered that does not
  * support the Serializable interface. In this case the
@@ -135,7 +134,8 @@
  * accessibility rules as writeReplace.<p>
  *
  * Enum types are all serializable and receive treatment defined by
- * the <cite>Java Object Serialization Specification</cite> during
+ * the <a href="{@docRoot}/../specs/serialization/index.html"><cite>
+ * Java Object Serialization Specification</cite></a> during
  * serialization and deserialization. Any declarations of the special
  * handling methods discussed above are ignored for enum types.<p>
  *
@@ -157,7 +157,8 @@
  * If a serializable class does not explicitly declare a serialVersionUID, then
  * the serialization runtime will calculate a default serialVersionUID value
  * for that class based on various aspects of the class, as described in the
- * Java Object Serialization Specification.  This specification defines the
+ * <a href="{@docRoot}/../specs/serialization/index.html"><cite>Java Object Serialization
+ * Specification.</cite></a> This specification defines the
  * serialVersionUID of an enum type to be 0L. However, it is <em>strongly
  * recommended</em> that all serializable classes other than enum types explicitly declare
  * serialVersionUID values, since the default serialVersionUID computation is
@@ -179,6 +180,8 @@
  * @see java.io.ObjectOutput
  * @see java.io.ObjectInput
  * @see java.io.Externalizable
+ * @see <a href="{@docRoot}/../specs/serialization/index.html">
+ *      <cite>Java Object Serialization Specification</cite></a>
  * @since   1.1
  */
 public interface Serializable {

src/java.base/share/classes/java/io/package-info.java

@@ -39,7 +39,7 @@
  * </strong></p>
  * <ul>
  *   <li><a href="{@docRoot}/../specs/serialization/index.html">
- *       Java Object Serialization Specification </a>
+ *       <cite>Java Object Serialization Specification</cite></a>
  *   <li>{@extLink serialization_filter_guide Serial Filtering} best practices</li>
  *   <li>{@extLink serialver_tool_reference The serialver tool}</li>
  * </ul>