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

[Mark Powers]

On Wed, 6 Jul 2022 20:46:44 GMT, Valerie Peng <valeriep at openjdk.org> wrote:

>> Mark Powers has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   aw shucks - another one
>
> src/java.base/share/classes/javax/crypto/Cipher.java line 144:
> 
>> 142:  * <p>
>> 143:  * Every implementation of the Java platform is required to support
>> 144:  * the following standard {@code Cipher} objecttransformations with the keysizes
> 
> typo: objecttransformations -> transformations

How did that happen? Fixed.

> src/java.base/share/classes/javax/crypto/Cipher.java line 1069:
> 
>> 1067: 
>> 1068:     /**
>> 1069:      * Returns the exemption mechanism object used with this {@code Cipher}.
> 
> Add object at the end.

Added.

> src/java.base/share/classes/javax/crypto/Cipher.java line 1223:
> 
>> 1221:      * <p>Note that when a {@code Cipher} object is initialized, it loses all
>> 1222:      * previously-acquired state. In other words, initializing a {@code Cipher}
>> 1223:      * object is equivalent to creating a new instance of that {@code Cipher}
> 
> add object to {@code Cipher} here?

Fixed.

> src/java.base/share/classes/javax/crypto/Cipher.java line 1801:
> 
>> 1799:      * doFinal() calls - should be initialized and in ENCRYPT_MODE or
>> 1800:      * DECRYPT_MODE.
>> 1801:      * @throws IllegalStateException if this {@code Cipher} objectis not in
> 
> typo: objectis -> object is

Fixed.

> src/java.base/share/classes/javax/crypto/Cipher.java line 2707:
> 
>> 2705:      * Calls to this method provide AAD to the {@code Cipher} object
>> 2706:      * when operating in modes such as AEAD (GCM/CCM).  If this
>> 2707:      * {@code Cipher} is operating in either GCM or CCM mode, all AAD
> 
> add object to {@code Cipher} here.

Fixed.

> src/java.base/share/classes/javax/crypto/Cipher.java line 2786:
> 
>> 2784:      * Calls to this method provide AAD to the {@code Cipher} object
>> 2785:      *  when operating in modes such as AEAD (GCM/CCM).  If this
>> 2786:      * {@code Cipher} is operating in either GCM or CCM mode, all AAD
> 
> add object to {@code Cipher} here.

Fixed.

> src/java.base/share/classes/javax/crypto/CipherOutputStream.java line 106:
> 
>> 104:      *
>> 105:      * Constructs a {@code CipherOutputStream} from an
>> 106:      * {@code OutputStream} and a {@code Cipher}.
> 
> add object to {@code Cipher} here.

Fixed.

> src/java.base/share/classes/javax/crypto/CipherOutputStream.java line 206:
> 
>> 204:      * <p>Any bytes buffered by the encapsulated {@code Cipher} object
>> 205:      * and waiting to be processed by it will not be written out. For example,
>> 206:      * if the encapsulated {@code Cipher} is a block cipher, and the
> 
> add object to {@code Cipher} here.

Fixed.

> src/java.base/share/classes/javax/crypto/CipherSpi.java line 301:
> 
>> 299: 
>> 300:     /**
>> 301:      * Initializes this {@code Cipher} object with a key and a source
> 
> Hmm, with this {@code } change, I think the class name should be `CipherSpi` instead of `Cipher`.
> This comment applies to the rest of this file.

Fixed. That's a lot of changes.

> src/java.base/share/classes/javax/crypto/CipherSpi.java line 385:
> 
>> 383:      * previously-acquired state. In other words, initializing a {@code Cipher}
>> 384:      * object is equivalent to creating a new instance of that
>> 385:      * {@code Cipher} and initializing it.
> 
> add object here.

Fixed.

> src/java.base/share/classes/javax/crypto/CipherSpi.java line 444:
> 
>> 442:      * {@code Cipher} object and initializing it.
>> 443:      *
>> 444:      * @param opmode the operation mode of this {@code Cipher} (this is one of
> 
> add object here.

Same comment appeared earlier. Odd. It's fixed.

> src/java.base/share/classes/javax/crypto/CipherSpi.java line 597:
> 
>> 595:      * decryption mode, and (un)padding has been requested, but the decrypted
>> 596:      * data is not bounded by the appropriate padding bytes
>> 597:      * @throws AEADBadTagException if this {@code Cipher} is decrypting in an
> 
> add object here.

Fixed.

> src/java.base/share/classes/javax/crypto/CipherSpi.java line 608:
> 
>> 606:      * Encrypts or decrypts data in a single-part operation,
>> 607:      * or finishes a multiple-part operation.
>> 608:      * The data is encrypted or decrypted, depending on how this {@code Cipher}
> 
> add object here.

Fixed.

> src/java.base/share/classes/javax/crypto/CipherSpi.java line 624:
> 
>> 622:      * a {@code ShortBufferException} is thrown.
>> 623:      *
>> 624:      * <p>Upon finishing, this method resets this {@code Cipher} to the state
> 
> add object here.

Fixed.

> src/java.base/share/classes/javax/crypto/CipherSpi.java line 631:
> 
>> 629:      * {@code engineInit}) more data.
>> 630:      *
>> 631:      * <p>Note: if any exception is thrown, this {@code Cipher} may need to
> 
> add object here.

Fixed.

> src/java.base/share/classes/javax/crypto/CipherSpi.java line 651:
> 
>> 649:      * @throws ShortBufferException if the given output buffer is too small
>> 650:      * to hold the result
>> 651:      * @throws BadPaddingException if this {@code Cipher} is in decryption mode,
> 
> add object here.

Fixed.

> src/java.base/share/classes/javax/crypto/CryptoAllPermission.java line 107:
> 
>> 105: /**
>> 106:  * A {@code CryptoAllPermissionCollection} stores a collection
>> 107:  * of {@code CryptoAllPermission} permissions.
> 
> maybe change "permissions" to "objects" to be consistent with the rest of this file?

Fixed.

> src/java.base/share/classes/javax/crypto/CryptoAllPermission.java line 158:
> 
>> 156:      *
>> 157:      * @return {@code true} if the given permission is implied by this
>> 158:      * CryptoAllPermissionCollection.
> 
> Add {@code }?

`{@code CryptoAllPermissionCollection}` object

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

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