From b08202a995008fb384e0b849e36569d79f715a1c Mon Sep 17 00:00:00 2001
From: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Date: Thu, 9 Jul 2015 18:54:21 +0000
Subject: [PATCH] doc: note about custom inspect functions

See: https://github.com/nodejs/io.js/issues/1798

When an Object is printed in REPL, the actual representation can be
overriden by defining `inspect` method on the objects. This patch
includes a note about the same in the REPL documentation
---
 doc/api/repl.markdown | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/doc/api/repl.markdown b/doc/api/repl.markdown
index 99cef9fcc706c1..a88d3d97ed0a67 100644
--- a/doc/api/repl.markdown
+++ b/doc/api/repl.markdown
@@ -237,3 +237,26 @@ The following key combinations in the REPL have these special effects:
   - `<ctrl>D` - Similar to the `.exit` keyword.
   - `<tab>` - Show both global and local(scope) variables
 
+
+### Overriding representation of Objects in REPL
+
+REPL module internally uses
+[`util.inspect`](https://iojs.org/api/util.html#util_util_inspect_object_options),
+ by default, to print the actual values. But, `util.inspect` delegates the call
+ to the object's `inspect` function, if it has one. You can read more about
+ this delegation,
+ [here](https://iojs.org/api/util.html#util_custom_inspect_function_on_objects).
+
+So, if you have defined an `inspect` function on an object, like this
+
+    > var obj = { foo: 'this will not show up in the inspect() output' };
+    undefined
+    > obj.inspect = function(depth) {
+    ...   return { bar: 'baz' };
+    ... };
+    [Function]
+
+and try to print `obj` in REPL, it will invoke the custom `inspect` function
+
+    > obj
+    { bar: 'baz' }