RFR: 8331008: Implement JEP 478: Key Derivation Function API (Preview) [v33]

[Weijun Wang]

On Fri, 13 Sep 2024 18:14:23 GMT, Kevin Driver <kdriver at openjdk.org> wrote:

>> src/java.base/share/classes/javax/crypto/spec/HKDFParameterSpec.java line 158:
>> 
>>> 156:          * be assembled piece-meal or if part of the IKM is to be supplied by a
>>> 157:          * hardware crypto device. This method appends to the existing list of
>>> 158:          * values or creates a new list if there is none yet.
>> 
>> Precisely, this should be "multiple addIKM may be called when..." since even in the simplest case you still need to call this method once. In fact, I don't think we need to talk about this detail every time. If you really want to emphasize this, create a section header with an anchor the class spec, and inside each method just say "This method can be called multiple times on a single Builder object. See class_section_name".
>> 
>> Appending to or creating a list is implementation detail.
>
> @wangweij: I have changed the wording, though I will leave these descriptions in-place. See: https://github.com/openjdk/jdk/pull/20301/commits/f513525c78aaf0797446c023329d22559eb39ac1.

I still think appending to or creating a list is implementation detail.

>> src/java.base/share/classes/javax/crypto/spec/HKDFParameterSpec.java line 248:
>> 
>>> 246: 
>>> 247:     /**
>>> 248:      * Returns a builder for building {@code Extract} and
>> 
>> Modify `builder` to `{@code Builder} object`.
>
> @wangweij: Addressed in https://github.com/openjdk/jdk/pull/20301/commits/f513525c78aaf0797446c023329d22559eb39ac1.

You can also append the `object` word here.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1759540848
PR Review Comment: https://git.openjdk.org/jdk/pull/20301#discussion_r1759541584