doc: reword stream docs to clarify that decodeStrings encodes strings

I was implementing a Writable stream and misunderstood `decodeStrings`
to mean 'will decode `Buffer`s into `string`s before calling `_write`'.
This change adds a little more detail to the description of
`decodeStrings` to clarify its effect on a Writable stream & what gets
passed to `_write`.

Changing the name of the option to `encodeStrings` would make it much
easier to understand, but the name was chosen in 2012 and the option
used in many projects (22k mentions of 'decodeStringsr in JS projects in
GitHub). Deprecating the old name & rolling out a replacement is beyond
my capabilities as a first-time contributor.

PR-URL: https://github.com/nodejs/node/pull/25468
Fixes: https://github.com/nodejs/node/issues/25464
Reviewed-By: Anna Henningsen <anna@addaleax.net>

1 files changed, 16 insertions, 10 deletions

diff --git a/doc/api/stream.md b/doc/api/stream.md
index c35c799129c..9e20370528f 100644
--- a/doc/api/stream.md
+++ b/doc/api/stream.md
@@ -1537,10 +1537,12 @@ changes:
   * `highWaterMark` {number} Buffer level when
     [`stream.write()`][stream-write] starts returning `false`. **Default:**
     `16384` (16kb), or `16` for `objectMode` streams.
-  * `decodeStrings` {boolean} Whether or not to encode strings as
-    `Buffer`s before passing them to [`stream._write()`][stream-_write],
-    using the encoding specified in the [`stream.write()`][stream-write] call.
-    **Default:** `true`.
+  * `decodeStrings` {boolean} Whether to encode `string`s passed to
+    [`stream.write()`][stream-write] to `Buffer`s (with the encoding
+    specified in the [`stream.write()`][stream-write] call) before passing
+    them to [`stream._write()`][stream-_write]. Other types of data are not
+    converted (i.e. `Buffer`s are not decoded into `string`s). Setting to
+    false will prevent `string`s from being converted.  **Default:** `true`.
   * `defaultEncoding` {string} The default encoding that is used when no
     encoding is specified as an argument to [`stream.write()`][stream-write].
     **Default:** `'utf8'`.
@@ -1606,9 +1608,11 @@ const myWritable = new Writable({
 
 #### writable.\_write(chunk, encoding, callback)
 
-* `chunk` {Buffer|string|any} The chunk to be written. Will **always**
-  be a buffer unless the `decodeStrings` option was set to `false`
-  or the stream is operating in object mode.
+* `chunk` {Buffer|string|any} The `Buffer` to be written, converted from the
+  `string` passed to [`stream.write()`][stream-write]. If the stream's
+  `decodeStrings` option is `false` or the stream is operating in object mode,
+  the chunk will not be converted & will be whatever was passed to
+  [`stream.write()`][stream-write].
 * `encoding` {string} If the chunk is a string, then `encoding` is the
   character encoding of that string. If chunk is a `Buffer`, or if the
   stream is operating in object mode, `encoding` may be ignored.
@@ -2301,9 +2305,11 @@ user programs.
 
 #### transform.\_transform(chunk, encoding, callback)
 
-* `chunk` {Buffer|string|any} The chunk to be transformed. Will **always**
-  be a buffer unless the `decodeStrings` option was set to `false`
-  or the stream is operating in object mode.
+* `chunk` {Buffer|string|any} The `Buffer` to be transformed, converted from
+  the `string` passed to [`stream.write()`][stream-write]. If the stream's
+  `decodeStrings` option is `false` or the stream is operating in object mode,
+  the chunk will not be converted & will be whatever was passed to
+  [`stream.write()`][stream-write].
 * `encoding` {string} If the chunk is a string, then this is the
   encoding type. If chunk is a buffer, then this is the special
   value - 'buffer', ignore it in this case.