From ce2838545bf2b99e48af8efec6231b84b56b44ef Mon Sep 17 00:00:00 2001
From: Natanael Log <natte.log@gmail.com>
Date: Sat, 1 Jul 2017 15:10:36 +0200
Subject: [PATCH] doc, util, console: clarify ambiguous docs

Add clarification to the documentation on util.format()
and console.log() regarding how excessive arguments are treated
when the first argument is a non-format string
compared to when it is not a string at all.

PR-URL: https://github.com/nodejs/node/pull/14027
Fixes: https://github.com/nodejs/node/issues/13908
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
---
 doc/api/console.md |  4 +---
 doc/api/util.md    | 11 ++++++-----
 2 files changed, 7 insertions(+), 8 deletions(-)

diff --git a/doc/api/console.md b/doc/api/console.md
index 5b687140253d26..f3652a56561316 100644
--- a/doc/api/console.md
+++ b/doc/api/console.md
@@ -227,9 +227,7 @@ console.log('count:', count);
 // Prints: count: 5, to stdout
 ```
 
-If formatting elements (e.g. `%d`) are not found in the first string then
-[`util.inspect()`][] is called on each argument and the resulting string
-values are concatenated. See [`util.format()`][] for more information.
+See [`util.format()`][] for more information.
 
 ### console.time(label)
 <!-- YAML
diff --git a/doc/api/util.md b/doc/api/util.md
index ec5ec635d16fdf..0ab3ba0390bc9d 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -116,16 +116,17 @@ util.format('%s:%s', 'foo');
 // Returns: 'foo:%s'
 ```
 
-If there are more arguments passed to the `util.format()` method than the
-number of placeholders, the extra arguments are coerced into strings (for
-objects and symbols, `util.inspect()` is used) then concatenated to the
-returned string, each delimited by a space.
+If there are more arguments passed to the `util.format()` method than the number
+of placeholders, the extra arguments are coerced into strings then concatenated
+to the returned string, each delimited by a space. Excessive arguments whose
+`typeof` is `'object'` or `'symbol'` (except `null`) will be transformed by
+`util.inspect()`.
 
 ```js
 util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'
 ```
 
-If the first argument is not a format string then `util.format()` returns
+If the first argument is not a string then `util.format()` returns
 a string that is the concatenation of all arguments separated by spaces.
 Each argument is converted to a string using `util.inspect()`.