util: custom inspect() method may return an Object

This is more like how `JSON.stringify()` works.
Closes #2711.

doc/api/util.markdown

@@ -114,6 +114,8 @@ Predefined color codes are: `white`, `grey`, `black`, `blue`, `cyan`,
 `green`, `magenta`, `red` and `yellow`.
 There are also `bold`, `italic`, `underline` and `inverse` codes.
 
+### Custom `inpect()` function on Objects
+
 Objects also may define their own `inspect(depth)` function which `util.inspect()`
 will invoke and use the result of when inspecting the object:
 
@@ -127,6 +129,18 @@ will invoke and use the result of when inspecting the object:
     util.inspect(obj);
       // "{nate}"
 
+You may also return another Object entirely, and the returned String will be
+formatted according to the returned Object. This is similar to how
+`JSON.stringify()` works:
+
+    var obj = { foo: 'this will not show up in the inspect() output' };
+    obj.inspect = function(depth) {
+      return { bar: 'baz' };
+    };
+
+    util.inspect(obj);
+      // "{ bar: 'baz' }"
+
 
 ## util.isArray(object)
 

lib/util.js

@@ -209,7 +209,11 @@ function formatValue(ctx, value, recurseTimes) {
       value.inspect !== exports.inspect &&
       // Also filter out any prototype objects using the circular check.
       !(value.constructor && value.constructor.prototype === value)) {
-    return String(value.inspect(recurseTimes));
+    var ret = value.inspect(recurseTimes);
+    if ('string' !== typeof ret) {
+      ret = formatValue(ctx, ret, recurseTimes);
+    }
+    return ret;
   }
 
   // Primitive types cannot have properties

test/simple/test-util-inspect.js

@@ -155,3 +155,8 @@ assert(util.inspect(subject, { customInspect: true }).indexOf('123') !== -1);
 assert(util.inspect(subject, { customInspect: true }).indexOf('inspect') === -1);
 assert(util.inspect(subject, { customInspect: false }).indexOf('123') === -1);
 assert(util.inspect(subject, { customInspect: false }).indexOf('inspect') !== -1);
+
+// custom inspect() functions should be able to return other Objects
+subject.inspect = function() { return { foo: 'bar' }; };
+
+assert.equal(util.inspect(subject), '{ foo: \'bar\' }');