RFR: 6587699: Document DigestInputStream behavior when skip() or mark() / reset() is used [v2]
Bradford Wetmore
wetmore at openjdk.org
Thu Jul 28 17:43:59 UTC 2022
On Thu, 28 Jul 2022 01:23:12 GMT, Weijun Wang <weijun at openjdk.org> wrote:
>> 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.
My feeling still remains. I don't recall seeing a wording construction like this except for IFF, which is well-understood. I think it could be said more compactly with:
`This implementation only updates the message digest with data actually read from the input stream when it is on. `
Just my $0.02.
>> 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.
Thanks. It's been a long time since I've looked at DigestInputStream, forgot about the on/off mode.
>> 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.
I meant additionally as in "here's an additional case to be aware of...", not "this is an additional read case..."
-------------
PR: https://git.openjdk.org/jdk/pull/9667
More information about the security-dev
mailing list