doc: stream.finished cleanup

doc/api/stream.md

@@ -1298,6 +1298,8 @@ added: REPLACEME
 * `stream` {Stream} A readable and/or writable stream.
 * `callback` {Function} A callback function that takes an optional error
   argument.
+* Returns: {Function} A cleanup function which removes all registered
+  listeners.
 
 A function to get notified when a stream is no longer readable, writable
 or has experienced an error or a premature close event.
@@ -1338,6 +1340,20 @@ run().catch(console.error);
 rs.resume(); // drain the stream
 ```
 
+`stream.finished()` leaves dangling event listeners (in particular
+`'error'`, `'end'`, `'finish'` and `'close'`) after `callback` has been
+invoked. The reason for this is so that unexpected `'error'` events (due to
+incorrect stream implementations) do not cause unexpected crashes.
+If this is unwanted behavior then the returned cleanup function needs to be
+invoked in the callback:
+
+```js
+const cleanup = finished(...streams, err => {
+  cleanup();
+  // ...
+});
+```
+
 ### stream.pipeline(...streams[, callback])
 <!-- YAML
 added: REPLACEME
@@ -1391,6 +1407,10 @@ async function run() {
 run().catch(console.error);
 ```
 
+`stream.pipeline()` leaves dangling event listeners on the streams
+after the `callback` has been invoked. In the case of reuse of streams after
+failure, this can cause event listener leaks and swallowed errors.
+
 ## API for Stream Implementers
 
 <!--type=misc-->