doc: make sure that calls to .read() are looped

doc/api/buffer.md

@@ -641,15 +641,16 @@ then copying out the relevant bits.
 const store = [];
 
 socket.on('readable', () => {
- const data = socket.read();
+ let data;
+ while (null !== (data = readable.read())) {
+ // Allocate for retained data
+ const sb = Buffer.allocUnsafeSlow(10);
 
- // Allocate for retained data
- const sb = Buffer.allocUnsafeSlow(10);
+  // Copy the data into the new allocation
+  data.copy(sb, 0, 0, 10);
 
- // Copy the data into the new allocation
- data.copy(sb, 0, 0, 10);
-
- store.push(sb);
+ store.push(sb);
+ }
 });
 ```
 
@@ -2561,15 +2562,16 @@ un-pooled `Buffer` instance using `SlowBuffer` then copy out the relevant bits.
 const store = [];
 
 socket.on('readable', () => {
- const data = socket.read();
+ let data;
+ while (null !== (data = readable.read())) {
+ // Allocate for retained data
+ const sb = SlowBuffer(10);
 
- // Allocate for retained data
- const sb = SlowBuffer(10);
+  // Copy the data into the new allocation
+  data.copy(sb, 0, 0, 10);
 
- // Copy the data into the new allocation
- data.copy(sb, 0, 0, 10);
-
- store.push(sb);
+ store.push(sb);
+ }
 });
 ```
 

doc/api/crypto.md

@@ -200,9 +200,10 @@ const cipher = crypto.createCipheriv(algorithm, key, iv);
 
 let encrypted = '';
 cipher.on('readable', () => {
- const data = cipher.read();
- if (data)
- encrypted += data.toString('hex');
+ let chunk;
+ while (null !== (chunk = cipher.read())) {
+ encrypted += chunk.toString('hex');
+ }
 });
 cipher.on('end', () => {
  console.log(encrypted);
@@ -383,9 +384,9 @@ const decipher = crypto.createDecipheriv(algorithm, key, iv);
 
 let decrypted = '';
 decipher.on('readable', () => {
- const data = decipher.read();
- if (data)
-  decrypted += data.toString('utf8');
+ while (null !== (chunk = decipher.read())) {
+  decrypted += chunk.toString('utf8');
+ }
 });
 decipher.on('end', () => {
  console.log(decrypted);
@@ -941,6 +942,8 @@ const crypto = require('crypto');
 const hash = crypto.createHash('sha256');
 
 hash.on('readable', () => {
+ // Only one element is going to be produced by the
+ // hash stream.
  const data = hash.read();
  if (data) {
  console.log(data.toString('hex'));
@@ -1033,6 +1036,8 @@ const crypto = require('crypto');
 const hmac = crypto.createHmac('sha256', 'a secret');
 
 hmac.on('readable', () => {
+ // Only one element is going to be produced by the
+ // hash stream.
  const data = hmac.read();
  if (data) {
  console.log(data.toString('hex'));
@@ -1756,6 +1761,8 @@ const hash = crypto.createHash('sha256');
 
 const input = fs.createReadStream(filename);
 input.on('readable', () => {
+ // Only one element is going to be produced by the
+ // hash stream.
  const data = input.read();
  if (data)
  hash.update(data);
@@ -1801,6 +1808,8 @@ const hmac = crypto.createHmac('sha256', 'a secret');
 
 const input = fs.createReadStream(filename);
 input.on('readable', () => {
+ // Only one element is going to be produced by the
+ // hash stream.
  const data = input.read();
  if (data)
  hmac.update(data);

doc/api/stream.md

@@ -1012,6 +1012,10 @@ readable.on('readable', () => {
 });
 ```
 
+Note that the `while` loop is necessary when processing data with
+`readable.read()`. Only after `readable.read()` returns `null`,
+[`'readable'`]() will be emitted.
+
 A `Readable` stream in object mode will always return a single item from
 a call to [`readable.read(size)`][stream-read], regardless of the value of the
 `size` argument.