RFR: 8209038: Clarify the javadoc of Cipher.getParameters() [v3]

[Weijun Wang]

On Thu, 28 Apr 2022 19:11:23 GMT, Valerie Peng <valeriep at openjdk.org> wrote:

>> Anyone can help review this javadoc update? The main change is the wording for the method javadoc of Cipher.getParameters()/CipherSpi.engineGetParameters(). The original wording is somewhat restrictive and request is to broaden this to accommodate more scenarios such as when null can be returned.
>> The rest are minor things like add {@code } to class name and null, and remove redundant ".". 
>> 
>> Will file CSR after the review is close to being wrapped up.
>> Thanks~
>
> Valerie Peng has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Update for getParameters()

src/java.base/share/classes/javax/crypto/Cipher.java line 1056:

> 1054:      * parameters were not supplied and the underlying cipher implementation
> 1055:      * can generate the parameter values, it will be returned. Otherwise,
> 1056:      * {@code null} returned.

Should this be "null is returned"?

src/java.base/share/classes/javax/crypto/Cipher.java line 1787:

> 1785:      * Ensures that Cipher is in a valid state for update() and doFinal()
> 1786:      * calls - should be initialized and in ENCRYPT_MODE or DECRYPT_MODE.
> 1787:      * @throws IllegalStateException if Cipher object is not in valid state

"Cipher" in `{@code}`? Or make it lowercase.

src/java.base/share/classes/javax/crypto/CipherSpi.java line 449:

> 447:      *
> 448:      * <p>Note that when a Cipher object is initialized, it loses all
> 449:      * previously-acquired state. In other words, initializing a Cipher is

Two `{@code Cipher}` above.

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

PR: https://git.openjdk.java.net/jdk/pull/8117