On 5/27/20 4:22 PM, Anthony Scarpino wrote:
Hi,
I need a javadoc review for a Signature/SignatureSpi parameters change
that is needed to the spec, which affects EdDSA. The existing spec was
very strict in the way set and get parameters were handled. This
modifies that slightly by allowing null to be returned by the get
methods when it is unsupported after the parameters have been set. Since
null was an allowed return value, this minimizes the backwards
compatibility chances.
CSR: https://bugs.openjdk.java.net/browse/JDK-8243425
webrev: https://cr.openjdk.java.net/~ascarpino/8243424/webrev/
Here are a few wording/formatting comments on Signature. The same
comments apply to SignatureSpi since it contains similar text.
1015 * (by calling the {@code setParameter} method) and the underlying
You should distinguish between the two overloaded setParameter methods
so it is clear which one you are talking about. I recommend using @link
instead of @code: {@link #setParameter(AlgorithmParameterSpec)}
1016 * implementation supports returning the parameters as
AlgorithmParameters,
I would say "underlying signature implementation" to be consistent with
the previous text.
Also, change "AlgorithmParameters" (the one above and below) to "{@code
AlgorithmParameters}".
1017 * this method returns the same parameters. If parameters are
set using
1018 * {@code setParameter}, this method may return those parameters
Use "{@link #setParameter(String, Object)}" instead of "{@code
setParameter}"
1019 * from the provider as AlgorithmParameters, if supported.
The first two sentences are very similar. How about combining them as:
"If this signature has been previously initialized with parameters
(by calling {@link #setParameter(AlgorithmParameterSpec)} or {@link
#setParameter(String, Object)}) and the underlying signature
implementation supports returning the parameters as {@code
AlgorithmParameters}, this method returns the same parameters."
1020 * parameters were not set, this method may return a combination
1021 * of default and randomly generated parameter values if the
1022 * underlying signature implementation supports it and can
successfully
1023 * generate them. Otherwise, {@code null} is returned.
--Sean
