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: #25468 Fixes: #25464 Reviewed-By: Anna Henningsen <anna@addaleax.net>
nodejs · May 16, 2019 · 6ae41bde4d17eac960edf33f9d6cae50b61b8203 · 6ae41bd
1 parent 33a9d17
commit 6ae41bde4d17eac960edf33f9d6cae50b61b8203
Showing with 16 additions and 10 deletions.

+16 −10 doc/api/stream.md
diff --git a/doc/api/stream.md b/doc/api/stream.md
@@ -1530,10 +1530,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'`.
@@ -1599,9 +1601,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.