From 7b5864e20228518dacc86f44d1c5680f7a5149a0 Mon Sep 17 00:00:00 2001
From: Rich Trott <rtrott@gmail.com>
Date: Tue, 26 Sep 2017 14:14:21 -0700
Subject: [PATCH 1/2] util: deprecate obj.inspect for custom inspection

The existence of `obj.inspect()` for custom inspection can cause people
to unintentionally break `console.log()` and friends. This is a
documentation-only deprecation that can hopefully land in 8.x.

Refs: https://github.com/nodejs/node/issues/15549
---
 doc/api/deprecations.md | 11 +++++++++++
 doc/api/util.md         | 21 +++------------------
 2 files changed, 14 insertions(+), 18 deletions(-)

diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
index c70f494c6ddada..3845acda7a7c50 100644
--- a/doc/api/deprecations.md
+++ b/doc/api/deprecations.md
@@ -700,6 +700,15 @@ Type: Runtime
 
 `REPLServer.turnOffEditorMode()` was removed from userland visibility.
 
+<a id="DEP00XX"></a>
+### DEP00XX: Custom inspection function on Objects via .inspect()
+
+Type: Documentation-only
+
+Using a property named `inspect` on an object to specify a custom inspection
+function for [`util.inspect()`][] is deprecated. Use [`util.inspect.custom`][]
+instead.
+
 [`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size
 [`Buffer.from(array)`]: buffer.html#buffer_class_method_buffer_from_array
 [`Buffer.from(buffer)`]: buffer.html#buffer_class_method_buffer_from_buffer
@@ -738,6 +747,8 @@ Type: Runtime
 [`util._extend()`]: util.html#util_util_extend_target_source
 [`util.debug()`]: util.html#util_util_debug_string
 [`util.error()`]: util.html#util_util_error_strings
+[`util.inspect()`]: util.html#util_util_inspect_object_options
+[`util.inspect.custom`]: util.html#util_util_inspect_custom
 [`util.isArray()`]: util.html#util_util_isarray_object
 [`util.isBoolean()`]: util.html#util_util_isboolean_object
 [`util.isBuffer()`]: util.html#util_util_isbuffer_object
diff --git a/doc/api/util.md b/doc/api/util.md
index ce56c50104dbc4..2653c01af1d4c9 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -377,8 +377,8 @@ terminals.
 <!-- type=misc -->
 
 Objects may also define their own `[util.inspect.custom](depth, opts)`
-(or, equivalently `inspect(depth, opts)`) function that `util.inspect()` will
-invoke and use the result of when inspecting the object:
+(or the equivalent but deprecated `inspect(depth, opts)`) function that
+`util.inspect()` will invoke and use the result of when inspecting the object:
 
 ```js
 const util = require('util');
@@ -388,7 +388,7 @@ class Box {
     this.value = value;
   }
 
-  inspect(depth, options) {
+  [util.inspect.custom](depth, options) {
     if (depth < 0) {
       return options.stylize('[Box]', 'special');
     }
@@ -427,21 +427,6 @@ util.inspect(obj);
 // Returns: "{ bar: 'baz' }"
 ```
 
-A custom inspection method can alternatively be provided by exposing
-an `inspect(depth, opts)` method on the object:
-
-```js
-const util = require('util');
-
-const obj = { foo: 'this will not show up in the inspect() output' };
-obj.inspect = function(depth) {
-  return { bar: 'baz' };
-};
-
-util.inspect(obj);
-// Returns: "{ bar: 'baz' }"
-```
-
 ### util.inspect.custom
 <!-- YAML
 added: v6.6.0

From 1a791e8c6027bb0328c072f8aed0e3f6f5ea0756 Mon Sep 17 00:00:00 2001
From: Rich Trott <rtrott@gmail.com>
Date: Fri, 29 Sep 2017 16:31:01 -0700
Subject: [PATCH 2/2] squash: suggestion from addaleax

---
 doc/api/deprecations.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md
index 3845acda7a7c50..cd82b898728a08 100644
--- a/doc/api/deprecations.md
+++ b/doc/api/deprecations.md
@@ -707,7 +707,8 @@ Type: Documentation-only
 
 Using a property named `inspect` on an object to specify a custom inspection
 function for [`util.inspect()`][] is deprecated. Use [`util.inspect.custom`][]
-instead.
+instead. (For backwards compatibility with Node.js prior to version 6.4.0, both
+may be specified.)
 
 [`Buffer.allocUnsafeSlow(size)`]: buffer.html#buffer_class_method_buffer_allocunsafeslow_size
 [`Buffer.from(array)`]: buffer.html#buffer_class_method_buffer_from_array