doc: clarify documentation of pipes and zlib objects

Document how pipes can be chained in readable.pipe().
Document that zlib.Zlib inherits from stream.Transform.

PR-URL: #22354
Fixes: #22341
Reviewed-By: Vse Mozhet Byt <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Ruben Bridgewater <[email protected]>
Reviewed-By: Trivikram Kamat <[email protected]>

Author: andreasg123

doc/api/stream.md

@@ -895,8 +895,8 @@ added: v0.9.4
 * `destination` {stream.Writable} The destination for writing data
 * `options` {Object} Pipe options
   * `end` {boolean} End the writer when the reader ends. **Default:** `true`.
-* Returns: {stream.Writable} making it possible to set up chains of piped
-  streams
+* Returns: {stream.Writable} The *destination*, allowing for a chain of pipes if
+  it is a [`Duplex`][] or a [`Transform`][] stream
 
 The `readable.pipe()` method attaches a [`Writable`][] stream to the `readable`,
 causing it to switch automatically into flowing mode and push all of its data

doc/api/zlib.md

@@ -397,6 +397,9 @@ added: v0.5.8
 Not exported by the `zlib` module. It is documented here because it is the base
 class of the compressor/decompressor classes.
 
+This class inherits from [`stream.Transform`][], allowing `zlib` objects to be
+used in pipes and similar stream operations.
+
 ### zlib.bytesRead
 <!-- YAML
 added: v8.1.0
@@ -840,6 +843,7 @@ Decompress a chunk of data with [`Unzip`][].
 [`InflateRaw`]: #zlib_class_zlib_inflateraw
 [`TypedArray`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
 [`Unzip`]: #zlib_class_zlib_unzip
+[`stream.Transform`]: stream.html#stream_class_stream_transform
 [`zlib.bytesWritten`]: #zlib_zlib_byteswritten
 [Memory Usage Tuning]: #zlib_memory_usage_tuning
 [pool size]: cli.html#cli_uv_threadpool_size_size