8263105: security-libs doclint cleanup

Reviewed-by: iris, darcy, dfuchs, mullan

src/java.base/share/classes/java/security/AccessControlException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2021, 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
@@ -46,7 +46,9 @@ public class AccessControlException extends SecurityException {
     @java.io.Serial
     private static final long serialVersionUID = 5138225684096988535L;
 
-    // the permission that caused the exception to be thrown.
+    /**
+     * The permission that caused the exception to be thrown.
+     */
     private Permission perm;
 
     /**

src/java.base/share/classes/java/security/AllPermission.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2021, 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
@@ -161,7 +161,10 @@ final class AllPermissionCollection
     @java.io.Serial
     private static final long serialVersionUID = -4023755556366636806L;
 
-    private boolean all_allowed; // true if any all permissions have been added
+    /**
+     * True if any AllPermissions have been added.
+     */
+    private boolean all_allowed;
 
     /**
      * Create an empty AllPermissions object.

src/java.base/share/classes/java/security/BasicPermission.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2021, 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
@@ -260,6 +260,10 @@ public abstract class BasicPermission extends Permission
     /**
      * readObject is called to restore the state of the BasicPermission from
      * a stream.
+     *
+     * @param  s the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     @java.io.Serial
     private void readObject(ObjectInputStream s)
@@ -488,13 +492,17 @@ final class BasicPermissionCollection
         new ObjectStreamField("permClass", Class.class),
     };
 
-    /**
+    /*
      * @serialData Default fields.
      */
-    /*
+
+    /**
      * Writes the contents of the perms field out as a Hashtable for
      * serialization compatibility with earlier releases. all_allowed
      * and permClass unchanged.
+     *
+     * @param  out the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     @java.io.Serial
     private void writeObject(ObjectOutputStream out) throws IOException {
@@ -517,6 +525,10 @@ final class BasicPermissionCollection
     /**
      * readObject is called to restore the state of the
      * BasicPermissionCollection from a stream.
+     *
+     * @param  in the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     @java.io.Serial
     private void readObject(java.io.ObjectInputStream in)

src/java.base/share/classes/java/security/CodeSigner.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2021, 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
@@ -48,7 +48,7 @@ public final class CodeSigner implements Serializable {
      */
     private CertPath signerCertPath;
 
-    /*
+    /**
      * The signature timestamp.
      *
      * @serial
@@ -165,7 +165,14 @@ public final class CodeSigner implements Serializable {
         return sb.toString();
     }
 
-    // Explicitly reset hash code value to -1
+    /**
+     * Restores the state of this object from the stream, and explicitly
+     * resets hash code value to -1.
+     *
+     * @param  ois the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
+     */
     @java.io.Serial
     private void readObject(ObjectInputStream ois)
         throws IOException, ClassNotFoundException {

src/java.base/share/classes/java/security/CodeSource.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2021, 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
@@ -522,6 +522,9 @@ public class CodeSource implements java.io.Serializable {
      * followed by the certificate encoding itself which is written out as an
      * array of bytes. Finally, if any code signers are present then the array
      * of code signers is serialized and written out too.
+     *
+     * @param  oos the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     @java.io.Serial
     private void writeObject(java.io.ObjectOutputStream oos)
@@ -557,6 +560,10 @@ public class CodeSource implements java.io.Serializable {
 
     /**
      * Restores this object from a stream (i.e., deserializes it).
+     *
+     * @param  ois the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     @java.io.Serial
     private void readObject(java.io.ObjectInputStream ois)

src/java.base/share/classes/java/security/GuardedObject.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2021, 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
@@ -25,6 +25,8 @@
 
 package java.security;
 
+import java.io.IOException;
+
 /**
  * A GuardedObject is an object that is used to protect access to
  * another object.
@@ -52,10 +54,17 @@ public class GuardedObject implements java.io.Serializable {
     @java.io.Serial
     private static final long serialVersionUID = -5240450096227834308L;
 
+    /**
+     * The object we are guarding.
+     */
     @SuppressWarnings("serial") // Not statically typed as Serializable
-    private Object object; // the object we are guarding
+    private Object object;
+
+    /**
+     * The guard object.
+     */
     @SuppressWarnings("serial") // Not statically typed as Serializable
-    private Guard guard;   // the guard
+    private Guard guard;
 
     /**
      * Constructs a GuardedObject using the specified object and guard.
@@ -94,10 +103,13 @@ public class GuardedObject implements java.io.Serializable {
     /**
      * Writes this object out to a stream (i.e., serializes it).
      * We check the guard if there is one.
+     *
+     * @param  oos the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     @java.io.Serial
     private void writeObject(java.io.ObjectOutputStream oos)
-        throws java.io.IOException
+        throws IOException
     {
         if (guard != null)
             guard.checkGuard(object);

src/java.base/share/classes/java/security/KeyPair.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2021, 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
@@ -44,7 +44,10 @@ public final class KeyPair implements java.io.Serializable {
     @java.io.Serial
     private static final long serialVersionUID = -7565189502268009837L;
 
+    /** The private key. */
     private PrivateKey privateKey;
+
+    /** The public key. */
     private PublicKey publicKey;
 
     /**

src/java.base/share/classes/java/security/Permission.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2021, 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
@@ -68,6 +68,9 @@ public abstract class Permission implements Guard, java.io.Serializable {
     @java.io.Serial
     private static final long serialVersionUID = -5636570222231596674L;
 
+    /**
+     * The permission name.
+     */
     private String name;
 
     /**

src/java.base/share/classes/java/security/PermissionCollection.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2021, 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
@@ -99,7 +99,11 @@ public abstract class PermissionCollection implements java.io.Serializable {
     @java.io.Serial
     private static final long serialVersionUID = -6727011328946861783L;
 
-    // when set, add will throw an exception.
+    /**
+     * Whether this permission collection is read-only.
+     * <p>
+     * If set, the {@code add} method will throw an exception.
+     */
     private volatile boolean readOnly;
 
     /**

src/java.base/share/classes/java/security/Permissions.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2021, 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
@@ -577,11 +577,11 @@ implements Serializable
     };
 
     /**
-     * @serialData Default fields.
-     */
-    /*
      * Writes the contents of the permsMap field out as a Hashtable for
      * serialization compatibility with earlier releases.
+     *
+     * @param  out the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     @java.io.Serial
     private void writeObject(ObjectOutputStream out) throws IOException {
@@ -598,9 +598,13 @@ implements Serializable
         out.writeFields();
     }
 
-    /*
+    /**
      * Reads in a Hashtable of Permission/Permission and saves them in the
      * permsMap field.
+     *
+     * @param  in the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     @java.io.Serial
     private void readObject(ObjectInputStream in) throws IOException,

src/java.base/share/classes/java/security/PrivilegedActionException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2021, 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
@@ -96,23 +96,28 @@ public class PrivilegedActionException extends Exception {
 
 
     /**
-     * Serializable fields for UndeclaredThrowableException.
+     * The exception thrown by the privileged computation that resulted
+     * in this {@code PrivilegedActionException}.
      *
-     * @serialField undeclaredThrowable Throwable
+     * @serialField exception Exception the thrown Exception
      */
     @java.io.Serial
     private static final ObjectStreamField[] serialPersistentFields = {
         new ObjectStreamField("exception", Exception.class)
     };
 
-    /*
+    /**
      * Reconstitutes the PrivilegedActionException instance from a stream
      * and initialize the cause properly when deserializing from an older
      * version.
      *
-     * The getException and getCause method returns the private "exception"
+     * <p>The getException and getCause method returns the private "exception"
      * field in the older implementation and PrivilegedActionException::cause
      * was set to null.
+     *
+     * @param  s the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     @java.io.Serial
     private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundException {
@@ -123,9 +128,12 @@ public class PrivilegedActionException extends Exception {
         }
     }
 
-    /*
+    /**
      * To maintain compatibility with older implementation, write a serial
      * "exception" field with the cause as the value.
+     *
+     * @param  out the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     @java.io.Serial
     private void writeObject(ObjectOutputStream out) throws IOException {

src/java.base/share/classes/java/security/Provider.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2021, 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
@@ -860,6 +860,8 @@ public abstract class Provider extends Properties {
     * is, then its double value will be used to populate both fields.
     *
     * @param in the {@code ObjectInputStream} to read
+    * @throws IOException if an I/O error occurs
+    * @throws ClassNotFoundException if a serialized class cannot be loaded
     * @serial
     */
     @java.io.Serial

src/java.base/share/classes/java/security/SecureRandom.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1996, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2021, 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
@@ -178,8 +178,8 @@ public class SecureRandom extends java.util.Random {
      */
     private final boolean threadSafe;
 
-    /*
+    /**
-     * The algorithm name of null if unknown.
+     * The algorithm name or {@code null} if unknown.
      *
      * @serial
      * @since 1.5

src/java.base/share/classes/java/security/SignedObject.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2021, 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
@@ -118,17 +118,23 @@ import java.io.*;
 
 public final class SignedObject implements Serializable {
 
-    @java.io.Serial
+    @Serial
     private static final long serialVersionUID = 720502720485447167L;
 
-    /*
+    /**
      * The original content is "deep copied" in its serialized format
-     * and stored in a byte array.  The signature field is also in the
+     * and stored in a byte array.
-     * form of byte array.
      */
-
     private byte[] content;
+
+    /**
+     * The signature field is stored as a byte array.
+     */
     private byte[] signature;
+
+    /**
+     * The algorithm used to sign the object.
+     */
     private String thealgorithm;
 
     /**
@@ -250,11 +256,15 @@ public final class SignedObject implements Serializable {
     /**
      * readObject is called to restore the state of the SignedObject from
      * a stream.
+     *
+     * @param  s the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
-    @java.io.Serial
+    @Serial
-    private void readObject(java.io.ObjectInputStream s)
+    private void readObject(ObjectInputStream s)
-        throws java.io.IOException, ClassNotFoundException {
+        throws IOException, ClassNotFoundException {
-            java.io.ObjectInputStream.GetField fields = s.readFields();
+            ObjectInputStream.GetField fields = s.readFields();
             content = ((byte[])fields.get("content", null)).clone();
             signature = ((byte[])fields.get("signature", null)).clone();
             thealgorithm = (String)fields.get("thealgorithm", null);

src/java.base/share/classes/java/security/Timestamp.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2003, 2021, 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
@@ -155,7 +155,14 @@ public final class Timestamp implements Serializable {
         return sb.toString();
     }
 
-    // Explicitly reset hash code value to -1
+    /**
+     * Restores the state of this object from the stream, and explicitly
+     * resets hash code value to -1.
+     *
+     * @param  ois the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
+     */
     @java.io.Serial
     private void readObject(ObjectInputStream ois)
         throws IOException, ClassNotFoundException {

src/java.base/share/classes/java/security/UnresolvedPermission.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2021, 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
@@ -521,6 +521,9 @@ implements java.io.Serializable
      * {@code int} specifying the length of the certificate encoding,
      * followed by the certificate encoding itself which is written out as an
      * array of bytes.
+     *
+     * @param  oos the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     @java.io.Serial
     private void writeObject(java.io.ObjectOutputStream oos)
@@ -550,6 +553,10 @@ implements java.io.Serializable
 
     /**
      * Restores this object from a stream (i.e., deserializes it).
+     *
+     * @param  ois the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     @java.io.Serial
     private void readObject(java.io.ObjectInputStream ois)

src/java.base/share/classes/java/security/UnresolvedPermissionCollection.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2021, 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
@@ -155,12 +155,12 @@ implements java.io.Serializable
     };
 
     /**
-     * @serialData Default field.
-     */
-    /*
      * Writes the contents of the perms field out as a Hashtable
      * in which the values are Vectors for
      * serialization compatibility with earlier releases.
+     *
+     * @param  out the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     @java.io.Serial
     private void writeObject(ObjectOutputStream out) throws IOException {
@@ -187,9 +187,13 @@ implements java.io.Serializable
         out.writeFields();
     }
 
-    /*
+    /**
      * Reads in a Hashtable in which the values are Vectors of
      * UnresolvedPermissions and saves them in the perms field.
+     *
+     * @param  in the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     @java.io.Serial
     private void readObject(ObjectInputStream in) throws IOException,

src/java.base/share/classes/java/security/cert/CertPath.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2021, 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
@@ -122,7 +122,8 @@ public abstract class CertPath implements Serializable {
     @java.io.Serial
     private static final long serialVersionUID = 6068470306649138683L;
 
-    private String type;        // the type of certificates in this chain
+    /** The type of certificates in this chain. */
+    private String type;
 
     /**
      * Creates a {@code CertPath} of the specified type.

src/java.base/share/classes/java/security/cert/CertPathValidatorException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2021, 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
@@ -229,6 +229,13 @@ public class CertPathValidatorException extends GeneralSecurityException {
         return this.reason;
     }
 
+    /**
+     * Restores the state of this object from the stream.
+     *
+     * @param  stream the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
+     */
     @java.io.Serial
     private void readObject(ObjectInputStream stream)
         throws ClassNotFoundException, IOException {

src/java.base/share/classes/java/security/cert/Certificate.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2021, 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
@@ -65,10 +65,10 @@ public abstract class Certificate implements java.io.Serializable {
     @java.io.Serial
     private static final long serialVersionUID = -3585440601605666277L;
 
-    // the certificate type
+    /** The certificate type. */
     private final String type;
 
-    /** Cache the hash code for the certiticate */
+    /** The hash code for the certificate. */
     private int hash = -1; // Default to -1
 
     /**
@@ -244,7 +244,10 @@ public abstract class Certificate implements java.io.Serializable {
         @java.io.Serial
         private static final long serialVersionUID = -8563758940495660020L;
 
+        /** The standard name of the certificate type. */
         private String type;
+
+        /** The certificate data. */
         private byte[] data;
 
         /**

src/java.base/share/classes/java/security/cert/CertificateRevokedException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2007, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2007, 2021, 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
@@ -192,6 +192,9 @@ public class CertificateRevokedException extends CertificateException {
      * the following data is emitted: the OID String (Object), the criticality
      * flag (boolean), the length of the encoded extension value byte array
      * (int), and the encoded extension value bytes.
+     *
+     * @param  oos the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     @java.io.Serial
     private void writeObject(ObjectOutputStream oos) throws IOException {
@@ -219,6 +222,10 @@ public class CertificateRevokedException extends CertificateException {
 
     /**
      * Deserialize the {@code CertificateRevokedException} instance.
+     *
+     * @param  ois the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     @java.io.Serial
     private void readObject(ObjectInputStream ois)

src/java.base/share/classes/java/util/Random.java

@@ -1179,6 +1179,10 @@ public class Random implements java.io.Serializable {
     /**
      * Reconstitute the {@code Random} instance from a stream (that is,
      * deserialize it).
+     *
+     * @param  s the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     @java.io.Serial
     private void readObject(java.io.ObjectInputStream s)
@@ -1199,6 +1203,9 @@ public class Random implements java.io.Serializable {
 
     /**
      * Save the {@code Random} instance to a stream.
+     *
+     * @param  s the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     @java.io.Serial
     private synchronized void writeObject(ObjectOutputStream s)

src/java.base/share/classes/javax/crypto/SealedObject.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1997, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1997, 2021, 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
@@ -421,8 +421,11 @@ public class SealedObject implements Serializable {
 
     /**
      * Restores the state of the SealedObject from a stream.
+     *
      * @param s the object input stream.
-     * @exception NullPointerException if s is null.
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
+     * @throws NullPointerException if s is null
      */
     @java.io.Serial
     private void readObject(java.io.ObjectInputStream s)

src/java.base/share/classes/javax/security/auth/PrivateCredentialPermission.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2021, 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
@@ -26,6 +26,7 @@
 package javax.security.auth;
 
 import java.util.*;
+import java.io.IOException;
 import java.text.MessageFormat;
 import java.security.Permission;
 import java.security.PermissionCollection;
@@ -475,10 +476,14 @@ public final class PrivateCredentialPermission extends Permission {
 
     /**
      * Reads this object from a stream (i.e., deserializes it)
+     *
+     * @param  s the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     @java.io.Serial
     private void readObject(java.io.ObjectInputStream s) throws
-                                        java.io.IOException,
+                                        IOException,
                                         ClassNotFoundException {
 
         s.defaultReadObject();

src/java.base/share/classes/javax/security/auth/Subject.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1998, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1998, 2021, 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
@@ -949,6 +949,9 @@ public final class Subject implements java.io.Serializable {
 
     /**
      * Writes this object out to a stream (i.e., serializes it).
+     *
+     * @param  oos the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     @java.io.Serial
     private void writeObject(java.io.ObjectOutputStream oos)
@@ -960,6 +963,10 @@ public final class Subject implements java.io.Serializable {
 
     /**
      * Reads this object from a stream (i.e., deserializes it)
+     *
+     * @param  s the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     @SuppressWarnings("unchecked")
     @java.io.Serial
@@ -1408,6 +1415,9 @@ public final class Subject implements java.io.Serializable {
          *      the caller has permission to access each credential
          *      in the set.  If the security check passes,
          *      the set is serialized.
+         *
+         * @param  oos the {@code ObjectOutputStream} to which data is written
+         * @throws IOException if an I/O error occurs
          */
         @java.io.Serial
         private void writeObject(java.io.ObjectOutputStream oos)
@@ -1427,6 +1437,13 @@ public final class Subject implements java.io.Serializable {
             oos.writeFields();
         }
 
+        /**
+         * Restores the state of this object from the stream.
+         *
+         * @param  ois the {@code ObjectInputStream} from which data is read
+         * @throws IOException if an I/O error occurs
+         * @throws ClassNotFoundException if a serialized class cannot be loaded
+         */
         @SuppressWarnings("unchecked")
         @java.io.Serial
         private void readObject(ObjectInputStream ois)

src/java.base/share/classes/javax/security/auth/x500/X500Principal.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2021, 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,6 +494,9 @@ public final class X500Principal implements Principal, java.io.Serializable {
      * @serialData this {@code X500Principal} is serialized
      *          by writing out its DER-encoded form
      *          (the value of {@code getEncoded} is serialized).
+     *
+     * @param  s the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     @java.io.Serial
     private void writeObject(java.io.ObjectOutputStream s)
@@ -503,6 +506,11 @@ public final class X500Principal implements Principal, java.io.Serializable {
 
     /**
      * Reads this object from a stream (i.e., deserializes it).
+     *
+     * @param  s the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws NotActiveException if serialization is not active
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     @java.io.Serial
     private void readObject(java.io.ObjectInputStream s)

src/java.security.jgss/share/classes/javax/security/auth/kerberos/DelegationPermission.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2021, 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
@@ -218,6 +218,9 @@ public final class DelegationPermission extends BasicPermission
      * WriteObject is called to save the state of the DelegationPermission
      * to a stream. The actions are serialized, and the superclass
      * takes care of the name.
+     *
+     * @param  s the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     private synchronized void writeObject(java.io.ObjectOutputStream s)
         throws IOException
@@ -228,6 +231,10 @@ public final class DelegationPermission extends BasicPermission
     /**
      * readObject is called to restore the state of the
      * DelegationPermission from a stream.
+     *
+     * @param  s the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     private synchronized void readObject(java.io.ObjectInputStream s)
          throws IOException, ClassNotFoundException

src/java.security.jgss/share/classes/javax/security/auth/kerberos/KerberosPrincipal.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2021, 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
@@ -265,6 +265,9 @@ public final class KerberosPrincipal
     /**
      * Save the {@code KerberosPrincipal} object to a stream
      *
+     * @param  oos the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
+     *
      * @serialData this {@code KerberosPrincipal} is serialized
      *          by writing out the PrincipalName and the
      *          Realm in their DER-encoded form as specified in Section 5.2.2 of
@@ -285,6 +288,10 @@ public final class KerberosPrincipal
 
     /**
      * Reads this object from a stream (i.e., deserializes it)
+     *
+     * @param  ois the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     private void readObject(ObjectInputStream ois)
             throws IOException, ClassNotFoundException {

src/java.security.jgss/share/classes/javax/security/auth/kerberos/KerberosTicket.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2021, 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
@@ -839,6 +839,13 @@ public class KerberosTicket implements Destroyable, Refreshable,
         return true;
     }
 
+    /**
+     * Restores the state of this object from the stream.
+     *
+     * @param  s the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
+     */
     private void readObject(ObjectInputStream s)
             throws IOException, ClassNotFoundException {
         s.defaultReadObject();

src/java.security.jgss/share/classes/javax/security/auth/kerberos/KeyImpl.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2021, 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
@@ -176,27 +176,39 @@ class KeyImpl implements SecretKey, Destroyable, Serializable {
     }
 
     /**
+     * Writes the state of this object to the stream.
+
      * @serialData this {@code KeyImpl} is serialized by
-     * writing out the ASN1 Encoded bytes of the encryption key.
+     * writing out the ASN.1 Encoded bytes of the encryption key.
-     * The ASN1 encoding is defined in RFC4120 and as  follows:
+     * The ASN.1 encoding is defined in RFC4120 as follows:
      * EncryptionKey   ::= SEQUENCE {
      *          keytype    [0] Int32 -- actually encryption type --,
      *          keyvalue   [1] OCTET STRING
+     *
+     * @param  oos the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      * }
      */
-    private void writeObject(ObjectOutputStream ois)
+    private void writeObject(ObjectOutputStream oos)
                 throws IOException {
         if (destroyed) {
            throw new IOException("This key is no longer valid");
         }
 
         try {
-           ois.writeObject((new EncryptionKey(keyType, keyBytes)).asn1Encode());
+           oos.writeObject((new EncryptionKey(keyType, keyBytes)).asn1Encode());
         } catch (Asn1Exception ae) {
            throw new IOException(ae.getMessage());
         }
     }
 
+    /**
+     * Restores the state of this object from the stream.
+     *
+     * @param  ois the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
+     */
     private void readObject(ObjectInputStream ois)
                 throws IOException, ClassNotFoundException {
         try {

src/java.security.jgss/share/classes/javax/security/auth/kerberos/ServicePermission.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2021, 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
@@ -425,6 +425,9 @@ public final class ServicePermission extends Permission
      * WriteObject is called to save the state of the ServicePermission
      * to a stream. The actions are serialized, and the superclass
      * takes care of the name.
+     *
+     * @param  s the {@code ObjectOutputStream} to which data is written
+     * @throws IOException if an I/O error occurs
      */
     private void writeObject(java.io.ObjectOutputStream s)
         throws IOException
@@ -439,6 +442,10 @@ public final class ServicePermission extends Permission
     /**
      * readObject is called to restore the state of the
      * ServicePermission from a stream.
+     *
+     * @param  s the {@code ObjectInputStream} from which data is read
+     * @throws IOException if an I/O error occurs
+     * @throws ClassNotFoundException if a serialized class cannot be loaded
      */
     private void readObject(java.io.ObjectInputStream s)
          throws IOException, ClassNotFoundException

src/java.xml.crypto/share/classes/javax/xml/crypto/URIReferenceException.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2021, 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
@@ -57,6 +57,10 @@ public class URIReferenceException extends Exception {
      */
     private Throwable cause;
 
+    /**
+     * The {@code URIReference} that was being dereferenced
+     * when the exception was thrown, or {@code null} if not specified.
+     */
     private URIReference uriReference;
 
     /**

src/jdk.security.auth/share/classes/com/sun/security/auth/PrincipalComparator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2021, 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
@@ -55,6 +55,8 @@ public interface PrincipalComparator {
      * Check if the specified {@code Subject} is implied by
      * this object.
      *
+     * @param  subject the subject to compare
+     *
      * @return true if the specified {@code Subject} is implied by
      *          this object, or false otherwise.
      */

src/jdk.security.auth/share/classes/com/sun/security/auth/module/JndiLoginModule.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2020, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2021, 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
@@ -151,8 +151,16 @@ import static sun.security.util.ResourcesMgr.getAuthResourceString;
  */
 public class JndiLoginModule implements LoginModule {
 
-    /** JNDI Provider */
+    /**
+     * Directory service/path where this module can access the relevent
+     * user information.
+     */
     public final String USER_PROVIDER = "user.provider.url";
+
+    /**
+     * Directory service/path where this module can access the relevent
+     * group information.
+     */
     public final String GROUP_PROVIDER = "group.provider.url";
 
     // configurable options

src/jdk.security.auth/share/classes/com/sun/security/auth/module/UnixSystem.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2000, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 2021, 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
@@ -34,9 +34,17 @@ public class UnixSystem {
     private native void getUnixInfo();
 
     // Warning: the following 4 fields are used by Unix.c
+
+    /** The current username. */
     protected String username;
+
+    /** The current user ID. */
     protected long uid;
+
+    /** The current group ID. */
     protected long gid;
+
+    /** The current list of groups. */
     protected long[] groups;
 
     /**