Doc improvements

1 files changed, 24 insertions, 2 deletions

diff --git a/doc/api/stdio.markdown b/doc/api/stdio.markdown
index d4153934e..45d8d3bca 100644
--- a/doc/api/stdio.markdown
+++ b/doc/api/stdio.markdown
@@ -9,8 +9,30 @@ Prints to stdout with newline. This function can take multiple arguments in a
 
     console.log('count: %d', count);
 
-If formating elements are not found in the first string then `util.inspect`
-is used on each argument.
+The first argument is a string that contains zero or more *placeholders*.
+Each placeholder is replaced with the converted value from its corresponding
+argument. Supported placeholders are:
+
+* `%s` - String.
+* `%d` - Number (both integer and float).
+* `%j` - JSON.
+
+If the placeholder does not have a corresponding argument, `undefined` is used.
+
+    console.log('%s:%s', 'foo'); // 'foo:undefined'
+
+If there are more arguments than placeholders, the extra arguments are
+converted to strings with `util.inspect()` and these strings are concatenated,
+delimited by a space.
+
+    console.log('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'
+
+If the first argument is not a format string then `console.log()` prints
+a string that is the concatenation of all its arguments separated by spaces.
+Each argument is converted to a string with `util.inspect()`.
+
+    console.log(1, 2, 3); // '1 2 3'
+
 
 ### console.info()