I am a little late to this thread, but some alternative verbiage to consider is included below. This wording however diverges from that of [1] so if we want them to remain similar then it’s probably not worth it to change from what has been agreed upon already.
Thanks, Brian [1] https://docs.oracle.com/javase/9/docs/api/java/io/InputStream.html#transferTo-java.io.OutputStream- 57 * Reads all characters from this source and writes the characters to 58 * the given appendable in the order that they are read. On return, the 59 * source of characters will be at its end. Reads all characters from this source and appends them to a destination in the order in which they are read. On return, ... 60 * <p> 61 * This method may block indefinitely reading from the readable, or 62 * writing to the appendable. Where this source or the appendable is 63 * {@link AutoCloseable closeable}, then the behavior when either are 64 * <i>asynchronously closed</i>, or the thread interrupted during the transfer, 65 * is highly readable and appendable specific, and therefore not specified. This method may block indefinitely while reading from the source or writing to the destination. If the source or destination is {@link AutoCloseable closeable}, then the behavior when either is <i>asynchronously closed</i>, or the thread is interrupted during the transfer, is highly implementation-dependent and hence unspecified. 66 * <p> 67 * If an I/O error occurs reading from the readable or writing to the 68 * appendable, then it may do so after some characters have been read or 69 * written. Consequently the readable may not be at end of its data and 70 * one, or both participants may be in an inconsistent state. That in mind 71 * all additional measures required by one or both participants in order to 72 * eventually free their internal resources have to be taken by the caller 73 * of this method. If an I/O error occurs during the operation, then not all characters might have been transferred and the source or destination could be left in an inconsistent state. The caller of this method should therefore ensure in such a case that measures are taken to release any resources held by the source and destination. On Nov 3, 2017, at 5:49 AM, Alan Bateman <alan.bate...@oracle.com> wrote: > On 02/11/2017 19:55, Patrick Reinhart wrote: >> : >> If we are all happy with the API so far, I could start adding an initial >> implementation and test… >> > I think the API looks fine so go ahead.
