From cd245b12e08de19f5ad6c261cfc2a77bc880dfc6 Mon Sep 17 00:00:00 2001
From: Martii <thalamew@q.com>
Date: Wed, 7 Oct 2015 21:14:16 -0600
Subject: [PATCH] doc: clarify API buffer.concat

* Add a simple example for buffer.concat
* Change grammar slightly.

Fixes: #3219
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trevor Norris <trev.norris@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/3255
---
 doc/api/buffer.markdown | 28 +++++++++++++++++++++++++++-
 1 file changed, 27 insertions(+), 1 deletion(-)

diff --git a/doc/api/buffer.markdown b/doc/api/buffer.markdown
index 0f3a2ff2f72c4d..c678c4a2da8b13 100644
--- a/doc/api/buffer.markdown
+++ b/doc/api/buffer.markdown
@@ -126,7 +126,7 @@ Example:
 ### Class Method: Buffer.concat(list[, totalLength])
 
 * `list` {Array} List of Buffer objects to concat
-* `totalLength` {Number} Total length of the buffers when concatenated
+* `totalLength` {Number} Total length of the buffers in the list when concatenated
 
 Returns a buffer which is the result of concatenating all the buffers in
 the list together.
@@ -138,6 +138,32 @@ If totalLength is not provided, it is read from the buffers in the list.
 However, this adds an additional loop to the function, so it is faster
 to provide the length explicitly.
 
+Example: build a single buffer from a list of three buffers:
+
+    var buf1 = new Buffer(10);
+    var buf2 = new Buffer(14);
+    var buf3 = new Buffer(18);
+
+    buf1.fill(0);
+    buf2.fill(0);
+    buf3.fill(0);
+
+    var buffers = [buf1, buf2, buf3];
+
+    var totalLength = 0;
+    for (var i = 0; i < buffers.length; i++) {
+      totalLength += buffers[i].length;
+    }
+
+    console.log(totalLength);
+    var bufA = Buffer.concat(buffers, totalLength);
+    console.log(bufA);
+    console.log(bufA.length);
+
+    // 42
+    // <Buffer 00 00 00 00 ...>
+    // 42
+
 ### Class Method: Buffer.compare(buf1, buf2)
 
 * `buf1` {Buffer}