doc: update writable.write return value

Tanuja-Sawant · evanlucas · commit 85d2a2abcf9a · 2017-01-04T10:44:02.000-06:00
stream.md is updated to explain the return value of writable.write(chunk) precisely. PR-URL: #9468 Fixes: #9247 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Ron Korving <ron@ronkorving.nl> Reviewed-By: Roman Reiss <me@silverwind.io>
diff --git a/doc/api/stream.md b/doc/api/stream.md
@@ -440,10 +440,12 @@ occurs, the `callback` *may or may not* be called with the error as its
 first argument. To reliably detect write errors, add a listener for the
 `'error'` event.
 
-The return value indicates whether the written `chunk` was buffered internally
-and the buffer has exceeded the `highWaterMark` configured when the stream was
-created. If `false` is returned, further attempts to write data to the stream
-should be paused until the [`'drain'`][] event is emitted.
+The return value is `true` if the internal buffer does not exceed
+`highWaterMark` configured when the stream was created after admitting `chunk`.
+If `false` is returned, further attempts to write data to the stream should
+stop until the [`'drain'`][] event is emitted. However, the `false` return
+value is only advisory and the writable stream will unconditionally accept and
+buffer `chunk` even if it has not not been allowed to drain.
 
 A Writable stream in object mode will always ignore the `encoding` argument.
 
