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

[Sean Mullan]

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()

Changes requested by mullan (Reviewer).

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

> 1051:      * <p>The returned parameters may be the same that were used to initialize
> 1052:      * this cipher, or may contain additional default or random parameter
> 1053:      * values used by the underlying cipher implementation. If the required

The PR for https://github.com/openjdk/jdk/pull/8396/ has one difference in this sentence in that it says "... values used by the underlying signature implementation _if the underlying signature implementation supports returning the parameters as {@code AlgorithmParameters}_." Should this also be consistent?

Also, I don't think you need to repeat "underlying signature " again above, you could just say: ... values used by the underlying signature implementation _if the implementation supports returning the parameters as {@code AlgorithmParameters}_."

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

> 1053:      * values used by the underlying cipher implementation. If the required
> 1054:      * parameters were not supplied and the underlying cipher implementation
> 1055:      * can generate the parameter values, it will be returned. Otherwise,

"it will be returned" sounds a bit awkward here. I would change this to "the generated parameter values will be returned".

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

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