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

Fri Jul 1 19:55:27 UTC 2022

On Tue, 28 Jun 2022 20:19:29 GMT, Weijun Wang <weijun at openjdk.org> wrote:

>> Mark Powers has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Valerie fix
>
> 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.

This conflicts with the previous recommendation. I ultimately changed "Provider object" to just "provider". The sentence flows much better.

> 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}`.

Changed "Provider object" to just "provider". The sentence flows much better.

> 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}`.

Fixed.

> 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}`.

Fixed.

> 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.

Fixed.

> 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.

JDK-8289581 Unintelligible comment in AllPermission add() method

> 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.

What is the JavaDoc change? Is this a code change?

> 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.

Changed to `{@code BasicPermission}` objects.

> 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?

made 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".

using "class"

> 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".

using `{@code 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".

Fixed.

> 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.

Fixed.

> 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".

Fixed.

> 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.

Fixed.

> 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".

Fixed.

> 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.

Fixed.

> 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".

Fixed.

> 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"?

Yes.

> 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.

Fixed.

> 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.

Fixed.

> 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".

using `{@code 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}`.

Fixed.

> 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.

Fixed.

> 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.

Fixed.

> 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.

Fixed.

> 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.

Fixed.

> 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.

Changed Object to `{@code Object}`  but changed "PermissionCollection's" to just "collection's".

> 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.

Fixed.

> src/java.base/share/classes/java/security/Permissions.java line 100:
> 
>> 98:     /**
>> 99:      * Creates a new {@code Permissions} object containing no
>> 100:      * PermissionCollections.
> 
> PermissionCollections.

changed to `{@code PermissionCollection}` objects

> 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.

Fixed.

> 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.

Fixed.

> 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.

Fixed.

> 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.

@return an enumeration of all the `{@code Permission}` objects.

> 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.

Fixed.

> 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.

Fixed.

> 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.

Fixed.

> 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.

Fixed.

> 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.

Fixed.

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

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