RFR: JDK-8284851 Update javax.crypto files to use proper javadoc for mentioned classes [v2]

Tue Jun 28 21:14:59 UTC 2022

On Tue, 28 Jun 2022 19:32:07 GMT, Mark Powers <duke at openjdk.org> wrote:

>> https://bugs.openjdk.org/browse/JDK-8284851
>
> Mark Powers has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Valerie fix

This is the `java.security` part.

src/java.base/share/classes/java/security/AccessController.java line 983:

> 981: 
> 982:     /**
> 983:      * Returns the "inherited" AccessControl context. This is the context

Not sure what "AccessControl context" is. Either "access control context" or "{@code AccessControlContext}".

src/java.base/share/classes/java/security/AccessController.java line 993:

> 991:     /**
> 992:      * This method takes a "snapshot" of the current calling context, which
> 993:      * includes the current Thread's inherited {@code AccessControlContext}

"Thread" to "thread".

src/java.base/share/classes/java/security/AccessController.java line 1021:

> 1019:      * the current {@code AccessControlContext} and security policy.
> 1020:      * This method quietly returns if the access request
> 1021:      * is permitted, or throws an AccessControlException otherwise. The

Want to code-if "AccessControlException" as well?

src/java.base/share/classes/java/security/AccessController.java line 1023:

> 1021:      * is permitted, or throws an AccessControlException otherwise. The
> 1022:      * {@code getPermission} method of the AccessControlException returns the
> 1023:      * {@code perm} {@code Permission} object instance.

Two "{@code" together. Maybe move "{@code perm}" to the end?

src/java.base/share/classes/java/security/AlgorithmParameterGenerator.java line 144:

> 142:      * A new {@code AlgorithmParameterGenerator} object encapsulating the
> 143:      * {@code AlgorithmParameterGeneratorSpi} implementation from the first
> 144:      * Provider that supports the specified algorithm is returned.

"Provider" -> "provider".

src/java.base/share/classes/java/security/AlgorithmParameterGenerator.java line 249:

> 247:      * <p> A new {@code AlgorithmParameterGenerator} object encapsulating the
> 248:      * {@code AlgorithmParameterGeneratorSpi} implementation from the Provider
> 249:      * object is returned.  Note that the specified Provider object

Code-ify two "Provider" here.

src/java.base/share/classes/java/security/AlgorithmParameters.java line 225:

> 223:      * <p> A new {@code AlgorithmParameters} object encapsulating the
> 224:      * {@code AlgorithmParametersSpi} implementation from the specified
> 225:      * Provider object is returned.  Note that the specified Provider object

`{@code Provider}`.

src/java.base/share/classes/java/security/AllPermission.java line 73:

> 71:      * Creates a new {@code AllPermission} object. This
> 72:      * constructor exists for use by the {@code Policy} object
> 73:      * to instantiate new Permission objects.

`{@code Permission}`.

src/java.base/share/classes/java/security/AllPermission.java line 139:

> 137: /**
> 138:  * An {@code AllPermissionCollection} stores a collection
> 139:  * of AllPermission permissions. {@code AllPermission} objects

`{@code AllPermission}`.

src/java.base/share/classes/java/security/AllPermission.java line 177:

> 175: 
> 176:     /**
> 177:      * Adds a permission to the {@code AllPermissions} object.

There is no such a thing named "AllPermissions". Update it into "AllPermissionCollection". There are several such names in this file.

src/java.base/share/classes/java/security/AllPermission.java line 178:

> 176:     /**
> 177:      * Adds a permission to the {@code AllPermissions} object.
> 178:      * The key for the hash is {@code permission.path}.

No idea what key means? Could possibly be describing an old implementation. File a separate bug please.

src/java.base/share/classes/java/security/AllPermission.java line 201:

> 199:     /**
> 200:      * Check and see if this set of permissions implies the permissions
> 201:      * expressed in "permission".

"this set of permissions" is not used anywhere. You can copy from the same method from the parent class.

src/java.base/share/classes/java/security/BasicPermission.java line 246:

> 244:     /**
> 245:      * Returns a new {@code PermissionCollection} object for storing
> 246:      * BasicPermissions.

Maybe the original wording is better. I found it strange to write `{@code BasicPermission}s`. There are several other occurrences in this file.

src/java.base/share/classes/java/security/BasicPermission.java line 250:

> 248:      * <p>{@code BasicPermission} objects must be stored in a manner
> 249:      * that allows them to be inserted in any order, but that also enables the
> 250:      * {@code PermissionCollection} {@code implies} method

Two code in a row. Maybe make it a link?

src/java.base/share/classes/java/security/BasicPermission.java line 360:

> 358:      *                                       {@code BasicPermission}, or if
> 359:      *                                       the permission is not of the
> 360:      *                                       same Class as the other

"Class" to "class" or "type".

src/java.base/share/classes/java/security/GeneralSecurityException.java line 52:

> 50:      * Constructs a {@code GeneralSecurityException} with the specified detail
> 51:      * message.
> 52:      * A detail message is a String that describes this particular

"String" to "string".

src/java.base/share/classes/java/security/IdentityScope.java line 38:

> 36:  *
> 37:  * <p>An {@code IdentityScope} can contain {@code Identity} objects of all
> 38:  * kinds, including Signers. All types of {@code Identity} objects can be

"Signers" -> "signers".

src/java.base/share/classes/java/security/IdentityScope.java line 190:

> 188:     /**
> 189:      * Retrieves the {@code Identity} whose name is the same as that of the
> 190:      * specified principal. (Note: Identity implements Principal.)

Code-ify both Identity and Principal.

src/java.base/share/classes/java/security/KeyStore.java line 1728:

> 1726:      * A new {@code KeyStore} object is returned that encapsulates the
> 1727:      * {@code KeyStoreSpi}
> 1728:      * implementation from the first Provider that supports the specified file.

"Provider" -> "provider".

src/java.base/share/classes/java/security/KeyStore.java line 1889:

> 1887:          * @throws KeyStoreException if an error occurred during the
> 1888:          *   operation
> 1889:          * @throws IllegalStateException if the getKeyStore method has

Code-ify getKeyStore.

src/java.base/share/classes/java/security/KeyStore.java line 1903:

> 1901:          *
> 1902:          * <p> This is useful if an existing {@code KeyStore} object needs to be
> 1903:          * used with Builder-based APIs.

"Builder" -> "builder".

src/java.base/share/classes/java/security/KeyStore.java line 1913:

> 1911:          * @throws IllegalArgumentException if the keyStore has not been
> 1912:          *   initialized
> 1913:          */

A bunch of names need to be in code above: Builder, KeyStore, ProtectionParameter, keyStore, protectionParameters. Same for the methods below.

src/java.base/share/classes/java/security/KeyStoreException.java line 44:

> 42:     /**
> 43:      * Constructs a {@code KeyStoreException} with no detail message.  (A
> 44:      * detail message is a String that describes this particular

"String" -> "string". Same below.

src/java.base/share/classes/java/security/MessageDigest.java line 266:

> 264:      * <p> A new {@code MessageDigest} object encapsulating the
> 265:      * {@code MessageDigestSpi} implementation from the specified Provider
> 266:      * object is returned.  Note that the specified Provider object

"Provider" -> "provider".

src/java.base/share/classes/java/security/MessageDigest.java line 562:

> 560:      * The following class allows providers to extend from
> 561:      * {@code MessageDigestSpi} rather than from {@code MessageDigest}.
> 562:      * It represents a MessageDigest with an

Maybe "message digest"?

src/java.base/share/classes/java/security/MessageDigest.java line 565:

> 563:      * encapsulated, provider-supplied SPI object (of type MessageDigestSpi).
> 564:      * If the provider implementation is an instance of
> 565:      * {@code MessageDigestSpi}, the getInstance() methods above return an

Wrap getInstance in code.

src/java.base/share/classes/java/security/MessageDigest.java line 569:

> 567:      *
> 568:      * Note: All SPI methods from the original MessageDigest class have been
> 569:      * moved up the hierarchy into a new class (MessageDigestSpi), which has

Both MessageDigest and MessageDigestSpi here.

src/java.base/share/classes/java/security/NoSuchProviderException.java line 43:

> 41:     /**
> 42:      * Constructs a {@code NoSuchProviderException} with no detail message. A
> 43:      * detail message is a String that describes this particular

"String" to "string".

src/java.base/share/classes/java/security/Permission.java line 52:

> 50:  * subset test.
> 51:  *
> 52:  * <P> {@code Permission} objects are similar to String objects in that they

`{@code String}`.

src/java.base/share/classes/java/security/PermissionCollection.java line 80:

> 78:  * it desires (one using a Hashtable, one using a Vector, etc.). For example,
> 79:  * the Permissions object uses a default {@code PermissionCollection}
> 80:  * implementation that stores the permission objects in a Hashtable.

Several names need to be wrapped in code in the two paragraphs above.

src/java.base/share/classes/java/security/PermissionCollection.java line 130:

> 128:     /**
> 129:      * Checks to see if the specified permission is implied by
> 130:      * the collection of Permission objects held in this

Permission.

src/java.base/share/classes/java/security/PermissionCollection.java line 175:

> 173:      * Marks this {@code PermissionCollection} object as "readonly". After
> 174:      * a {@code PermissionCollection} object
> 175:      * is marked as readonly, no new Permission objects can be added to it

Permission.

src/java.base/share/classes/java/security/PermissionCollection.java line 184:

> 182:     /**
> 183:      * Returns true if this {@code PermissionCollection} object is marked
> 184:      * as readonly. If it is readonly, no new Permission objects can be added

Permission.

src/java.base/share/classes/java/security/PermissionCollection.java line 211:

> 209:      * method of this
> 210:      * object's superclass, which is Object. The result is
> 211:      * this PermissionCollection's type name followed by this object's

Object, PermissionCollection.

src/java.base/share/classes/java/security/Permissions.java line 64:

> 62:  * PermissionCollection that uses a hashtable will be created and used. Each
> 63:  * hashtable entry stores a Permission object as both the key and the value.
> 64:  *

Multiple Permission and PermissionCollection.

src/java.base/share/classes/java/security/Permissions.java line 100:

> 98:     /**
> 99:      * Creates a new {@code Permissions} object containing no
> 100:      * PermissionCollections.

PermissionCollections.

src/java.base/share/classes/java/security/Permissions.java line 117:

> 115:      * if an appropriate collection does not yet exist.
> 116:      *
> 117:      * @param permission the Permission object to add.

Permission on L117, PermissionCollection on L108 and L114. FilePermission and FilePermissionCollection on Line 110.

src/java.base/share/classes/java/security/Permissions.java line 154:

> 152:      * specifies "read" access for  all files in all subdirectories of the
> 153:      * "/tmp" directory, and another FilePermission that specifies "write"
> 154:      * access for all files in the "/tmp/scratch/foo" directory.

FilePermissionCollection and FIlePermission (twice) above.

src/java.base/share/classes/java/security/Permissions.java line 188:

> 186:     /**
> 187:      * Returns an enumeration of all the Permission objects in all the
> 188:      * PermissionCollections in this {@code Permissions} object.

Permission and PermissionCollection.

src/java.base/share/classes/java/security/Permissions.java line 190:

> 188:      * PermissionCollections in this {@code Permissions} object.
> 189:      *
> 190:      * @return an enumeration of all the Permissions.

Permissions. This one need to be taken care of because it's about permission objects inside, not Permissions as in this class name.

src/java.base/share/classes/java/security/Permissions.java line 205:

> 203:      * For example, if <i>p</i> is a FilePermission,
> 204:      * the FilePermissionCollection
> 205:      * stored in this {@code Permissions} object will be returned.

PermissionCollection, FilePermission, FilePermissionCollection.

src/java.base/share/classes/java/security/Permissions.java line 208:

> 206:      *
> 207:      * If createEmpty is true,
> 208:      * this method creates a new PermissionCollection object for the specified

createEmpty and PermissionCollection.

src/java.base/share/classes/java/security/Permissions.java line 220:

> 218:      * createEmpty is true, then
> 219:      * this method instantiates and stores a default PermissionCollection
> 220:      * that uses a hashtable to store its permission objects.

PermissionCollection on L216 and 219.

src/java.base/share/classes/java/security/Policy.java line 50:

> 48:  * {@code getPolicy} installs an instance of the default Policy
> 49:  * implementation (a default subclass implementation of this abstract class).
> 50:  * The default Policy implementation can be changed by setting the value

Policy.

src/java.base/share/classes/java/security/Policy.java line 371:

> 369:      * A new {@code Policy} object encapsulating the
> 370:      * {@code PolicySpi} implementation from the first
> 371:      * Provider that supports the specified type is returned.

"Provider" to "provider", L368 and L371.

src/java.base/share/classes/java/security/Policy.java line 505:

> 503:      * <p> A new {@code Policy} object encapsulating the
> 504:      * {@code PolicySpi} implementation from the specified Provider
> 505:      * object is returned.  Note that the specified Provider object

Provider, twice.

src/java.base/share/classes/java/security/Policy.java line 517:

> 515:      * {@code null}.
> 516:      *
> 517:      * @param provider the Provider.

Provider.

src/java.base/share/classes/java/security/Policy.java line 581:

> 579:      * Otherwise this method returns {@code null}.
> 580:      *
> 581:      * @return the Provider of this Policy, or {@code null}.

Provider, L575/577/581. Maybe "provider". Or wrap in code.

src/java.base/share/classes/java/security/Policy.java line 596:

> 594:      * Otherwise this method returns {@code null}.
> 595:      *
> 596:      * @return the type of this Policy, or {@code null}.

Policy, L590/596.

src/java.base/share/classes/java/security/Policy.java line 611:

> 609:      * Otherwise this method returns {@code null}.
> 610:      *
> 611:      * @return Policy parameters, or {@code null}.

Policy, L605/611.

src/java.base/share/classes/java/security/ProtectionDomain.java line 53:

> 51:  * policies, a {@code ProtectionDomain} can also be constructed such that it
> 52:  * is dynamically mapped to a set of permissions by the current Policy whenever
> 53:  * a permission is checked.

Policy, L50/52.

src/java.base/share/classes/java/security/ProtectionDomain.java line 166:

> 164:      * Permissions object.
> 165:      * <p>
> 166:      * The permissions granted to this domain are static, i.e.

CodeSource, Permissions. Note it's PermissionCollection here. So maybe use "permissions".

src/java.base/share/classes/java/security/ProtectionDomain.java line 192:

> 190:     /**
> 191:      * Creates a new {@code ProtectionDomain} qualified by the given CodeSource,
> 192:      * Permissions, ClassLoader and array of Principals. If the

Same as above, plus ClassLoader and Principal.

src/java.base/share/classes/java/security/ProtectionDomain.java line 241:

> 239:     /**
> 240:      * Returns the CodeSource of this domain.
> 241:      * @return the CodeSource of this domain which may be {@code null}.

CodeSource.

src/java.base/share/classes/java/security/ProtectionDomain.java line 251:

> 249:     /**
> 250:      * Returns the ClassLoader of this domain.
> 251:      * @return the ClassLoader of this domain which may be {@code null}.

ClassLoader.

src/java.base/share/classes/java/security/ProtectionDomain.java line 298:

> 296:     /**
> 297:      * Check and see if this {@code ProtectionDomain} implies the permissions
> 298:      * expressed in the Permission object.

Permission.

src/java.base/share/classes/java/security/ProtectionDomain.java line 458:

> 456:      *          debug is {@code null},
> 457:      *          caller has Policy.getPolicy permission
> 458:      */

Maybe it's not necessary to fix these non-public API cases.

src/java.base/share/classes/java/security/ProviderException.java line 52:

> 50: 
> 51:     /**
> 52:      * Constructs a {@code ProviderException} with the specified detail

String, L43/53. I'm now wondering if we need to describe what detail message means at all.

src/java.base/share/classes/java/security/Security.java line 1032:

> 1030:      * Returns a Set of Strings containing the names of all available
> 1031:      * algorithms or types for the specified Java cryptographic service
> 1032:      * (e.g., Signature, MessageDigest, Cipher, Mac, KeyStore). Returns

All these Java cryptographic service type names.

src/java.base/share/classes/java/security/Security.java line 1033:

> 1031:      * algorithms or types for the specified Java cryptographic service
> 1032:      * (e.g., Signature, MessageDigest, Cipher, Mac, KeyStore). Returns
> 1033:      * an empty Set if there is no provider that supports the

"set" is OK.

src/java.base/share/classes/java/security/Security.java line 1034:

> 1032:      * (e.g., Signature, MessageDigest, Cipher, Mac, KeyStore). Returns
> 1033:      * an empty Set if there is no provider that supports the
> 1034:      * specified service or if serviceName is {@code null}. For a complete list

`{@code serviceName}`.

src/java.base/share/classes/java/security/UnresolvedPermission.java line 67:

> 65:  * containing information about the permission.
> 66:  *
> 67:  * <p>Later, when code calls AccessController.checkPermission

AccessController.checkPermission. Maybe make it a link.

src/java.base/share/classes/java/security/UnresolvedPermission.java line 329:

> 327:      * @param obj the object we are testing for equality with this object.
> 328:      *
> 329:      * @return true if obj is an {@code UnresolvedPermission}, and has the same

`{@code obj}`.

-------------

PR: https://git.openjdk.org/jdk/pull/9282