RFR: 8318677: (ch) Add implNote about minBufferCap to main variant of Channels.newWriter [v3]

[Alan Bateman]

On Wed, 25 Oct 2023 13:24:05 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> Brian Burkhalter has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   8318677: Correct the faux pas of the previous commit
>
> src/java.base/share/classes/java/nio/channels/Channels.java line 538:
> 
>> 536:      *         The minimum capacity of the internal byte buffer,
>> 537:      *         or {@code -1} if an implementation-dependent
>> 538:      *         default capacity is to be used; may be ignored
> 
> I'm not understanding this. The implNote says it *is* ignored, the annotation on the @param says *may*.
> 
> 
>      *         The minimum capacity of the internal byte buffer,
>      *         or {@code -1} if an implementation-dependent default capacity is to be used.
>      *         The minimum capacity is ignored.

> I'm not understanding this. The implNote says it _is_ ignored, the annotation on the @param says _may_.

The spec allows the value to be ignored, the JDK implementation ignores the value. So it's spec vs. implementation.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16325#discussion_r1371761296