3 files changed, 35 insertions, 20 deletions
diff --git a/doc/api/buffer.md b/doc/api/buffer.md
index 13267b710a..4f28095a92 100644
--- a/doc/api/buffer.md
+++ b/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);
+  }
 });
 ```
 
diff --git a/doc/api/crypto.md b/doc/api/crypto.md
index 2605393878..54bbf7794e 100644
--- a/doc/api/crypto.md
+++ b/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'));
@@ -1762,6 +1767,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);
@@ -1807,6 +1814,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);
diff --git a/doc/api/stream.md b/doc/api/stream.md
index 9650245345..b8b456f043 100644
--- a/doc/api/stream.md
+++ b/doc/api/stream.md
@@ -1011,6 +1011,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.