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

[Hamlin Li]

On Tue, 2 Feb 2021 08:39:16 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> Hamlin Li has refreshed the contents of this pull request, and previous commits have been removed. The incremental views will show differences compared to the previous content of the PR. The pull request contains one new commit since the last revision:
>> 
>>   JDK-8260694: (fc) Add apiNote to FileChannel.transferFrom to better describe "no bytes available" case
>
> 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?

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

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