8251182: Fix "no comment" warnings in java.naming

Reviewed-by: lancea, rriggs, dfuchs

src/java.naming/share/classes/javax/naming/CompositeName.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2020, 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
@@ -562,12 +562,19 @@ public Object remove(int posn) throws InvalidNameException{
     }
 
     /**
-     * Overridden to avoid implementation dependency.
+     * The writeObject method is called to save the state of the
+     * {@code CompositeName} to a stream.
+     *
      * @serialData The number of components (an {@code int}) followed by
      * the individual components (each a {@code String}).
+     *
+     * @param s the {@code ObjectOutputStream} to write to
+     * @throws java.io.IOException if an I/O error occurs
      */
+    @java.io.Serial
     private void writeObject(java.io.ObjectOutputStream s)
             throws java.io.IOException {
+        // Overridden to avoid implementation dependency
         s.writeInt(size());
         Enumeration<String> comps = getAll();
         while (comps.hasMoreElements()) {
@@ -576,10 +583,20 @@ private void writeObject(java.io.ObjectOutputStream s)
     }
 
     /**
-     * Overridden to avoid implementation dependency.
+     * The readObject method is called to restore the state of
+     * the {@code CompositeName} from a stream.
+     *
+     * See {@code writeObject} for a description of the serial form.
+     *
+     * @param s the {@code ObjectInputStream} to read from
+     * @throws java.io.IOException if an I/O error occurs
+     * @throws ClassNotFoundException if the class of a serialized object
+     *         could not be found
      */
+    @java.io.Serial
     private void readObject(java.io.ObjectInputStream s)
             throws java.io.IOException, ClassNotFoundException {
+        // Overridden to avoid implementation dependency
         impl = new NameImpl(null);  // null means use default syntax
         int n = s.readInt();    // number of components
         try {
@@ -594,6 +611,7 @@ private void readObject(java.io.ObjectInputStream s)
     /**
      * Use serialVersionUID from JNDI 1.1.1 for interoperability
      */
+    @java.io.Serial
     private static final long serialVersionUID = 1667768148915813118L;
 
 /*

src/java.naming/share/classes/javax/naming/CompoundName.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2020, 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
@@ -547,13 +547,20 @@ public Object remove(int posn) throws InvalidNameException {
     }
 
     /**
-     * Overridden to avoid implementation dependency.
+     * The writeObject method is called to save the state of the
+     * {@code CompoundName} to a stream.
+     *
      * @serialData The syntax {@code Properties}, followed by
      * the number of components (an {@code int}), and the individual
      * components (each a {@code String}).
+     *
+     * @param s the {@code ObjectOutputStream} to write to
+     * @throws java.io.IOException if an I/O error occurs
      */
+    @java.io.Serial
     private void writeObject(java.io.ObjectOutputStream s)
             throws java.io.IOException {
+        // Overridden to avoid implementation dependency
         s.writeObject(mySyntax);
         s.writeInt(size());
         Enumeration<String> comps = getAll();
@@ -563,10 +570,20 @@ private void writeObject(java.io.ObjectOutputStream s)
     }
 
     /**
-     * Overridden to avoid implementation dependency.
+     * The readObject method is called to restore the state of
+     * the {@code CompoundName} from a stream.
+     *
+     * See {@code writeObject} for a description of the serial form.
+     *
+     * @param s the {@code ObjectInputStream} to read from
+     * @throws java.io.IOException if an I/O error occurs
+     * @throws ClassNotFoundException if the class of a serialized object
+     *         could not be found
      */
+    @java.io.Serial
     private void readObject(java.io.ObjectInputStream s)
             throws java.io.IOException, ClassNotFoundException {
+        // Overridden to avoid implementation dependency.
         mySyntax = (Properties)s.readObject();
         impl = new NameImpl(mySyntax);
         int n = s.readInt();    // number of components
@@ -582,6 +599,7 @@ private void readObject(java.io.ObjectInputStream s)
     /**
      * Use serialVersionUID from JNDI 1.1.1 for interoperability
      */
+    @java.io.Serial
     private static final long serialVersionUID = 3513100557083972036L;
 
 /*

src/java.naming/share/classes/javax/naming/directory/BasicAttribute.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2020, 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
@@ -494,13 +494,20 @@ public DirContext getAttributeDefinition() throws NamingException {
 //  ---- serialization methods
 
     /**
-     * Overridden to avoid exposing implementation details
-     * @serialData Default field (the attribute ID -- a String),
-     * followed by the number of values (an int), and the
+     * The writeObject method is called to save the state of the
+     * {@code BasicAttribute} to a stream.
+     *
+     * @serialData Default field (the attribute ID - a {@code String}),
+     * followed by the number of values (an {@code int}), and the
      * individual values.
+     *
+     * @param s the {@code ObjectOutputStream} to write to
+     * @throws java.io.IOException if an I/O error occurs
      */
+    @java.io.Serial
     private void writeObject(java.io.ObjectOutputStream s)
             throws java.io.IOException {
+        // Overridden to avoid exposing implementation details
         s.defaultWriteObject(); // write out the attrID
         s.writeInt(values.size());
         for (int i = 0; i < values.size(); i++) {
@@ -509,10 +516,20 @@ private void writeObject(java.io.ObjectOutputStream s)
     }
 
     /**
-     * Overridden to avoid exposing implementation details.
+     * The readObject method is called to restore the state of
+     * the {@code BasicAttribute} from a stream.
+     *
+     * See {@code writeObject} for a description of the serial form.
+     *
+     * @param s the {@code ObjectInputStream} to read from
+     * @throws java.io.IOException if an I/O error occurs
+     * @throws ClassNotFoundException if the class of a serialized object
+     *         could not be found
      */
+    @java.io.Serial
     private void readObject(java.io.ObjectInputStream s)
             throws java.io.IOException, ClassNotFoundException {
+        // Overridden to avoid exposing implementation details.
         s.defaultReadObject();  // read in the attrID
         int n = s.readInt();    // number of values
         values = new Vector<>(Math.min(1024, n));
@@ -553,5 +570,6 @@ public void close() throws NamingException {
     /**
      * Use serialVersionUID from JNDI 1.1.1 for interoperability.
      */
+    @java.io.Serial
     private static final long serialVersionUID = 6743528196119291326L;
 }

src/java.naming/share/classes/javax/naming/directory/BasicAttributes.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2020, 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
@@ -279,13 +279,20 @@ public int hashCode() {
     }
 
     /**
-     * Overridden to avoid exposing implementation details.
-     * @serialData Default field (ignoreCase flag -- a boolean), followed by
+     * The writeObject method is called to save the state of the
+     * {@code BasicAttributes} to a stream.
+     *
+     * @serialData Default field (ignoreCase flag - a {@code boolean}), followed by
      * the number of attributes in the set
-     * (an int), and then the individual Attribute objects.
+     * (an {@code int}), and then the individual {@code Attribute} objects.
+     *
+     * @param s the {@code ObjectOutputStream} to write to
+     * @throws java.io.IOException if an I/O error occurs
      */
+    @java.io.Serial
     private void writeObject(java.io.ObjectOutputStream s)
             throws java.io.IOException {
+        // Overridden to avoid exposing implementation details
         s.defaultWriteObject(); // write out the ignoreCase flag
         s.writeInt(attrs.size());
         Enumeration<Attribute> attrEnum = attrs.elements();
@@ -295,10 +302,20 @@ private void writeObject(java.io.ObjectOutputStream s)
     }
 
     /**
-     * Overridden to avoid exposing implementation details.
+     * The readObject method is called to restore the state of
+     * the {@code BasicAttributes} from a stream.
+     *
+     * See {@code writeObject} for a description of the serial form.
+     *
+     * @param s the {@code ObjectInputStream} to read from
+     * @throws java.io.IOException if an I/O error occurs
+     * @throws ClassNotFoundException if the class of a serialized object
+     *         could not be found
      */
+    @java.io.Serial
     private void readObject(java.io.ObjectInputStream s)
             throws java.io.IOException, ClassNotFoundException {
+        // Overridden to avoid exposing implementation details.
         s.defaultReadObject();  // read in the ignoreCase flag
         int n = s.readInt();    // number of attributes
         attrs = (n >= 1)
@@ -374,5 +391,6 @@ public void close() throws NamingException {
     /**
      * Use serialVersionUID from JNDI 1.1.1 for interoperability.
      */
+    @java.io.Serial
     private static final long serialVersionUID = 4980164073184639448L;
 }

src/java.naming/share/classes/javax/naming/ldap/LdapName.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2020, 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
@@ -106,6 +106,8 @@ public class LdapName implements Name {
 
     private transient List<Rdn> rdns;   // parsed name components
     private transient String unparsed;  // if non-null, the DN in unparsed form
+
+    @java.io.Serial
     private static final long serialVersionUID = -1595520034788997356L;
 
     /**
@@ -755,17 +757,36 @@ public int hashCode() {
     }
 
     /**
+     * The writeObject method is called to save the state of the
+     * {@code LdapName} to a stream.
+     *
      * Serializes only the unparsed DN, for compactness and to avoid
      * any implementation dependency.
      *
-     * @serialData      The DN string
+     * @serialData The DN {@code String} representation of this LDAP name.
+     *
+     * @param s the {@code ObjectOutputStream} to write to
+     * @throws java.io.IOException if an I/O error occurs
      */
+    @java.io.Serial
     private void writeObject(ObjectOutputStream s)
             throws java.io.IOException {
         s.defaultWriteObject();
         s.writeObject(toString());
     }
 
+    /**
+     * The readObject method is called to restore the state of
+     * the {@code LdapName} from a stream.
+     *
+     * See {@code writeObject} for a description of the serial form.
+     *
+     * @param s the {@code ObjectInputStream} to read from
+     * @throws java.io.IOException if an I/O error occurs
+     * @throws ClassNotFoundException if the class of a serialized object
+     *         could not be found
+     */
+    @java.io.Serial
     private void readObject(ObjectInputStream s)
             throws java.io.IOException, ClassNotFoundException {
         s.defaultReadObject();

src/java.naming/share/classes/javax/naming/ldap/Rdn.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2020, 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
@@ -110,6 +110,7 @@ public class Rdn implements Serializable, Comparable<Object> {
     // The common case.
     private static final int DEFAULT_SIZE = 1;
 
+    @java.io.Serial
     private static final long serialVersionUID = -5994465067210009656L;
 
     /**
@@ -732,17 +733,36 @@ private static boolean isWhitespace(char c) {
     }
 
     /**
+     * The writeObject method is called to save the state of the
+     * {@code Rdn} to a stream.
+     *
      * Serializes only the unparsed RDN, for compactness and to avoid
      * any implementation dependency.
      *
-     * @serialData      The RDN string
+     * @serialData The unparsed RDN {@code String} representation.
+     *
+     * @param s the {@code ObjectOutputStream} to write to
+     * @throws java.io.IOException if an I/O error occurs
      */
+    @java.io.Serial
     private void writeObject(ObjectOutputStream s)
             throws java.io.IOException {
         s.defaultWriteObject();
         s.writeObject(toString());
     }
 
+    /**
+     * The readObject method is called to restore the state of
+     * the {@code Rdn} from a stream.
+     *
+     * See {@code writeObject} for a description of the serial form.
+     *
+     * @param s the {@code ObjectInputStream} to read from
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if the class of a serialized object
+     *         could not be found
+     */
+    @java.io.Serial
     private void readObject(ObjectInputStream s)
             throws IOException, ClassNotFoundException {
         s.defaultReadObject();

src/java.naming/share/classes/javax/naming/spi/NamingManager.java

@@ -948,6 +948,10 @@ public static Context getContinuationContext(CannotProceedException cpe)
         return (answer != null) ? answer : obj;
     }
 
+    /**
+     * Thrown when an error is encountered while loading and instantiating the
+     * context factory classes.
+     */
     private static class FactoryInitializationError extends Error {
         @java.io.Serial
         static final long serialVersionUID = -5805552256848841560L;