From a3f6854724090a3de77c2659cab55ff0f3b9ed34 Mon Sep 17 00:00:00 2001
From: "Ryan Scheel (Havvy)" <ryan.havvy@gmail.com>
Date: Sat, 1 Oct 2016 00:56:16 +0000
Subject: [PATCH] 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 | 30 ++++++++++++++++++++++++------
 1 file changed, 24 insertions(+), 6 deletions(-)

diff --git a/doc/api/util.md b/doc/api/util.md
index 3ffefa3f87fe31..57ed7269f68b87 100644
--- a/doc/api/util.md
+++ b/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' };
-obj[util.inspect.custom] = function(depth) {
-  return `{${this.name}}`;
-};
+class Box {
+  constructor(value) {
+    this.value = value;
+  }
 
-util.inspect(obj);
-  // "{nate}"
+  inspect(depth, options) {
+    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