RFR: JDK-8260694: (fc) Add apiNote to FileChannel.transferFrom to better describe "no bytes available" case [v2]

[Brian Burkhalter]

On Wed, 3 Feb 2021 01:15:40 GMT, Hamlin Li <mli at openjdk.org> wrote:

>> src/java.base/share/classes/java/nio/channels/FileChannel.java line 666:
>> 
>>> 664:      * transferred, it will not return -1, e.g. in case of EOF of the
>>> 665:      * {@code src} parameter.
>>> 666:      *
>> 
>> Looking at this again, I think it may be better if we just add a sentence to the end of the second paragraph of the method description. The second paragraph already covers the case that fewer bytes are transferred. I think it can be something simple like "No bytes are transferred if the source channel has reached end-of-stream". I suggest "end-of-stream" rather than "EOF" because that is the phrase used in the RBC javadoc.
>
> Hi Alan, Thanks for reviewing.
> I will add the sentence you suggested at the end of second paragraph, will use "end-of-stream".
> Still think it's better to add an apiNote, although it's a little redundant, but it helps emphasize it, I saw several cases of misunderstanding of transferFrom. How do you think about it?

Given the other verbiage I don't think that an `apiNote` is actually necessary.

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

PR: https://git.openjdk.java.net/jdk/pull/2329