doc: clarify undocumented stream properties

Fixes: #28592 Signed-off-by: James M Snell <[email protected]> PR-URL: #36715 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Rich Trott <[email protected]> Reviewed-By: Robert Nagy <[email protected]> Reviewed-By: Michaël Zasso <[email protected]>
nodejs · Jan 3, 2021 · 7cfa1be · 7cfa1be
1 parent 5499caa
commit 7cfa1be
Showing 1 changed file with 6 additions and 2 deletions.
diff --git a/doc/api/stream.md b/doc/api/stream.md
@@ -75,8 +75,7 @@ object mode is not safe.
 <!--type=misc-->
 
 Both [`Writable`][] and [`Readable`][] streams will store data in an internal
-buffer that can be retrieved using `writable.writableBuffer` or
-`readable.readableBuffer`, respectively.
+buffer.
 
 The amount of data potentially buffered depends on the `highWaterMark` option
 passed into the stream's constructor. For normal streams, the `highWaterMark`
@@ -120,6 +119,11 @@ writing data *to* the socket. Because data may be written to the socket at a
 faster or slower rate than data is received, each side should
 operate (and buffer) independently of the other.
 
+The mechanics of the internal buffering are an internal implementation detail
+and may be changed at any time. However, for certain advanced implementations,
+the internal buffers can be retrieved using `writable.writableBuffer` or
+`readable.readableBuffer`. Use of these undocumented properties is discouraged.
+
 ## API for stream consumers
 
 <!--type=misc-->