doc, util, console: clarify ambiguous docs

nattelog · MylesBorins · commit 7f6f1c2ddcf6 · 2017-08-15T20:57:35.000-07:00
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: #14027 Fixes: #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>
diff --git 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
@@ -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()`.
 
