doc: stream: clarify meaning of 'drain' some more

Courtesy of Lee Coltrane (@coltrane).

diff --git a/doc/api/stream.markdown b/doc/api/stream.markdown
index e02765af2f4c460842fe66a610f62758a6a1e9f8..5e0c6f642db77bffa456f7ca3aa5c47639a453e0 100644 (file)
--- a/doc/api/stream.markdown
+++ b/doc/api/stream.markdown
@@ -123,6 +123,10 @@ A `Writable Stream` has the following methods, members, and events.
 Emitted when the stream's write queue empties and it's safe to write without
 buffering again. Listen for it when `stream.write()` returns `false`.
 
+The `'drain'` event can happen at *any* time, regardless of whether or not
+`stream.write()` has previously returned `false`. To avoid receiving unwanted
+`'drain'` events, listen using `stream.once()`.
+
 ### Event: 'error'
 
 `function (exception) { }`