document more clearly that stdin will emit multiple readable events

nodejs · anentropic · Apr 22, 2019 · Apr 9, 2020 · Apr 9, 2020 · 990e4a6c7d47ce6c0e9c8f984cb3157c4b75a5a7
commit 990e4a6c7d47ce6c0e9c8f984cb3157c4b75a5a7
diff --git a/doc/api/process.md b/doc/api/process.md
@@ -2254,29 +2254,57 @@ The `process.stdin` property returns a stream connected to
 stream) unless fd `0` refers to a file, in which case it is
 a [Readable][] stream.
 
+As a [Duplex][] stream, `process.stdin` can also be used in "old" mode that
+is compatible with scripts written for Node.js prior to v0.10.
+For more information see [Stream compatibility][].
+
+In "old" streams mode the `stdin` stream is paused by default, so one
+must call `process.stdin.resume()` to read from it. Note also that calling
+`process.stdin.resume()` itself would switch stream to "old" mode.
+
 ```js
 process.stdin.setEncoding('utf8');
 
+// 'readable' may be triggered multiple times as data is buffered in
 process.stdin.on('readable', () => {
   let chunk;
-  // Use a loop to make sure we read all available data.
+  // Use a loop to make sure we read all currently available data
   while ((chunk = process.stdin.read()) !== null) {
     process.stdout.write(`data: ${chunk}`);
   }
 });
 
+// 'end' will be triggered once when there is no more data available
 process.stdin.on('end', () => {
   process.stdout.write('end');
 });
 ```
 
-As a [Duplex][] stream, `process.stdin` can also be used in "old" mode that
-is compatible with scripts written for Node.js prior to v0.10.
-For more information see [Stream compatibility][].
+Each call to `stdin.read()` returns a chunk of data. The chunks are not
+concatenated. A `while` loop is necessary to consume all data currently in the
+buffer. When reading a large file `.read()` may return `null`, having
+consumed all buffered content so far, but there is still more data to come not
+yet buffered. In this case a new `'readable'` event will be emitted when there
+is more data in the buffer. Finally the `'end'` event will be emitted when
+there is no more data to come.
 
-In "old" streams mode the `stdin` stream is paused by default, so one
-must call `process.stdin.resume()` to read from it. Note also that calling
-`process.stdin.resume()` itself would switch stream to "old" mode.
+Therefore to read a file's whole contents from `stdin` you need to collect
+chunks across multiple `'readable'` events, something like:
+
+```js
+var chunks = [];
+
+process.stdin.on('readable', () => {
+  let chunk;
+  while ((chunk = process.stdin.read()) !== null) {
+    chunks.push(chunk);
+  }
+});
+
+process.stdin.on('end', () => {
+  let content = chunks.join('');
+});
+```
 
 ### `process.stdin.fd`