buffer, doc: misc. fix and cleanup

* Add official documentation that a Buffer instance is a viable
  argument when instantiating a new Buffer.
* Properly set the poolOffset when a buffer needs to be truncated.
* Add comments clarifying specific peculiar coding choices.
* Remove a level of unnecessary indentation.

Signed-off-by: Trevor Norris <trev.norris@gmail.com>

Author: trevnorris

doc/api/buffer.markdown

@@ -72,6 +72,12 @@ will be thrown here.
 
 Allocates a new buffer using an `array` of octets.
 
+### new Buffer(buffer)
+
+* `buffer` {Buffer}
+
+Copies the passed `buffer` data onto a new `Buffer` instance.
+
 ### new Buffer(str[, encoding])
 
 * `str` String - string to encode.

lib/buffer.js

@@ -49,17 +49,24 @@ function Buffer(subject, encoding) {
   if (!util.isBuffer(this))
     return new Buffer(subject, encoding);
 
-  if (util.isNumber(subject))
+  if (util.isNumber(subject)) {
     this.length = subject > 0 ? subject >>> 0 : 0;
-  else if (util.isString(subject))
-    this.length = Buffer.byteLength(subject, encoding = encoding || 'utf8');
-  else if (util.isObject(subject)) {
+
+  } else if (util.isString(subject)) {
+    if (!util.isString(encoding) || encoding.length === 0)
+      encoding = 'utf8';
+    this.length = Buffer.byteLength(subject, encoding);
+
+  // Handle Arrays, Buffers, Uint8Arrays or JSON.
+  } else if (util.isObject(subject)) {
     if (subject.type === 'Buffer' && util.isArray(subject.data))
       subject = subject.data;
-
+    // Must use floor() because array length may be > kMaxLength.
     this.length = +subject.length > 0 ? Math.floor(+subject.length) : 0;
-  } else
+
+  } else {
     throw new TypeError('must start with number, buffer, array or string');
+  }
 
   if (this.length > kMaxLength) {
     throw new RangeError('Attempt to allocate Buffer larger than maximum ' +
@@ -79,25 +86,31 @@ function Buffer(subject, encoding) {
     alloc(this, this.length);
   }
 
-  if (!util.isNumber(subject)) {
-    if (util.isString(subject)) {
-      // In the case of base64 it's possible that the size of the buffer
-      // allocated was slightly too large. In this case we need to rewrite
-      // the length to the actual length written.
-      var len = this.write(subject, encoding);
-
-      // Buffer was truncated after decode, realloc internal ExternalArray
-      if (len !== this.length) {
-        this.length = len;
-        truncate(this, this.length);
-      }
-    } else {
-      if (util.isBuffer(subject))
-        subject.copy(this, 0, 0, this.length);
-      else if (util.isNumber(subject.length) || util.isArray(subject))
-        for (var i = 0; i < this.length; i++)
-          this[i] = subject[i];
+  if (util.isNumber(subject)) {
+    return;
+  }
+
+  if (util.isString(subject)) {
+    // In the case of base64 it's possible that the size of the buffer
+    // allocated was slightly too large. In this case we need to rewrite
+    // the length to the actual length written.
+    var len = this.write(subject, encoding);
+    // Buffer was truncated after decode, realloc internal ExternalArray
+    if (len !== this.length) {
+      var prevLen = this.length;
+      this.length = len;
+      truncate(this, this.length);
+      poolOffset -= (prevLen - len);
     }
+
+  } else if (util.isBuffer(subject)) {
+    subject.copy(this, 0, 0, this.length);
+
+  } else if (util.isNumber(subject.length) || util.isArray(subject)) {
+    // Really crappy way to handle Uint8Arrays, but V8 doesn't give a simple
+    // way to access the data from the C++ API.
+    for (var i = 0; i < this.length; i++)
+      this[i] = subject[i];
   }
 }