8263105: security-libs doclint cleanup

Reviewed-by: iris, darcy, dfuchs, mullan

Author: Bradford Wetmore

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 PermissionCollection newPermissionCollection() {
     /**
      * 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 @@ public Enumeration<Permission> elements() {
         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 @@ private void writeObject(ObjectOutputStream out) throws IOException {
     /**
      * 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 String toString() {
         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 String toString() {
      * 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 @@ private void writeObject(java.io.ObjectOutputStream oos)
 
     /**
      * 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 Object getObject()
     /**
      * 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 @@ public Enumeration<Permission> elements() {
     };
 
     /**
-     * @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 @@ private void writeObject(ObjectOutputStream out) throws IOException {
         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 String toString() {
 
 
     /**
-     * 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 @@ private void readObject(ObjectInputStream s) throws IOException, ClassNotFoundEx
         }
     }
 
-    /*
+    /**
      * 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 @@ private void putId() {
     * 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