doc: more realistic custom inspect example

Changes the custom inspect example to a more complex object that
actually uses the parameters of the custom inspect function. I
specifically chose a wrapper of a value called a "Box" that inspects
to "Box < inner_inspect_value >".

I also want there to be documentation explaining what the code is
actually doing. E.g., the padding replacement part is to make the
inspected value line up properly when multi-line inputs are given.

I also went with having a space between the Box's brackets and the inner
value because it matches how objects work, and that should definitely be
listed as a convention somewhere in here.

Also, the convention to shorten only when depth is less than 0, not e.g.
at 0.

But I don't know how to write the documentation for that, so I'm leaving
that to somebody who reads this message.

Ref: https://github.com/nodejs/node/issues/8442
PR-URL: https://github.com/nodejs/node/pull/8875
Reviewed-By: Evan Lucas <evanlucas@me.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>

doc/api/util.md

@@ -286,13 +286,31 @@ invoke and use the result of when inspecting the object:
 ```js
 const util = require('util');
 
-const obj = { name: 'nate' };
+class Box {
-obj[util.inspect.custom] = function(depth) {
+  constructor(value) {
-  return `{${this.name}}`;
+    this.value = value;
-};
+  }
 
-util.inspect(obj);
+  inspect(depth, options) {
-  // "{nate}"
+    if (depth < 0) {
+      return options.stylize('[Box]', 'special');
+    }
+
+    const newOptions = Object.assign({}, options, {
+      depth: options.depth === null ? null : options.depth - 1
+    });
+
+    // Five space padding because that's the size of "Box< ".
+    const padding = ' '.repeat(5);
+    const inner = util.inspect(this.value, newOptions).replace(/\n/g, '\n' + padding);
+    return options.stylize('Box', 'special') + '< ' + inner + ' >';
+  }
+}
+
+const box = new Box(true);
+
+util.inspect(box);
+  // "Box< true >"
 ```
 
 Custom `[util.inspect.custom](depth, opts)` functions typically return a string