RFR: 6587699: Document DigestInputStream behavior when skip() or mark() / reset() is used

[Weijun Wang]

On Thu, 28 Jul 2022 01:09:13 GMT, Bradford Wetmore <wetmore at openjdk.org> wrote:

> I'll approve this after CSR is approved.

Can you approve the PR when you're OK with the text? Unless the CSR is approved I won't be able to integrate it anyway. I usually wait for the PR to be approved first before writing the CSR so I don't need to update text on both sides.

> src/java.base/share/classes/java/security/DigestInputStream.java line 54:
> 
>> 52:  * digest to be computed, leaving the original digest untouched.
>> 53:  *
>> 54:  * @implNote This implementation updates and only updates the message digest
> 
> The "updates and only updates" feel awkward.  Maybe just the one mention of update?

I'm using the "if and only if" style, which means other non-read methods will not update the message digest.

> src/java.base/share/classes/java/security/DigestInputStream.java line 55:
> 
>> 53:  *
>> 54:  * @implNote This implementation updates and only updates the message digest
>> 55:  *      with data actually read from the input stream when it is turned on.
> 
> "when it is turned on"?  You could probably just end with "actually read from the input stream."

This is about the `on(boolean)` method. I just want to be precise.

> src/java.base/share/classes/java/security/DigestInputStream.java line 57:
> 
>> 55:  *      with data actually read from the input stream when it is turned on.
>> 56:  *      This includes various {@code read} methods, {@code transferTo},
>> 57:  *      {@code readAllBytes}, and {@code readNBytes}. Specifically, data
> 
> Specifically
> ->
> Additionally ?

Maybe I should use "especially". This is not "additionally" because `skip` is not one of these "read"-methods.

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

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