doc: document the custom "inspect()" function behavior

Closes #3361.

1 files changed, 13 insertions, 0 deletions

diff --git a/doc/api/util.markdown b/doc/api/util.markdown
index 2c1b7634b..58bbfb7e0 100644
--- a/doc/api/util.markdown
+++ b/doc/api/util.markdown
@@ -88,6 +88,19 @@ Example of inspecting all properties of the `util` object:
 
     console.log(util.inspect(util, true, null));
 
+Objects also may define their own `inspect(depth)` function which `util.inspect()`
+will invoke and use the result of when inspecting the object:
+
+    var util = require('util');
+
+    var obj = { name: 'nate' };
+    obj.inspect = function(depth) {
+      return '{' + this.name + '}';
+    };
+
+    util.inspect(obj);
+      // "{nate}"
+
 
 ## util.isArray(object)