doc: document Console class

document Console class to tell user can use it.

PR-URL: https://github.com/iojs/io.js/pull/1388
Fixes: https://github.com/iojs/io.js/issues/1359
Reviewed-By: Roman Reiss <me@silverwind.io>

doc/api/console.markdown

@@ -1,7 +1,17 @@
-# console
+# Console
 
     Stability: 2 - Stable
 
+The module defines a `Console` class and exports a `console` object.
+
+The `console` object is a special instance of `Console` whose output is
+sent to stdout or stderr.
+
+For ease of use, `console` is defined as a global object and can be used
+directly without `require`.
+
+## console
+
 * {Object}
 
 <!--type=global-->
@@ -22,7 +32,7 @@ In daily use, the blocking/non-blocking dichotomy is not something you
 should worry about unless you log huge amounts of data.
 
 
-## console.log([data][, ...])
+### console.log([data][, ...])
 
 Prints to stdout with newline. This function can take multiple arguments in a
 `printf()`-like way. Example:
@@ -34,19 +44,19 @@ Prints to stdout with newline. This function can take multiple arguments in a
 If formatting elements are not found in the first string then `util.inspect`
 is used on each argument.  See [util.format()][] for more information.
 
-## console.info([data][, ...])
+### console.info([data][, ...])
 
 Same as `console.log`.
 
-## console.error([data][, ...])
+### console.error([data][, ...])
 
 Same as `console.log` but prints to stderr.
 
-## console.warn([data][, ...])
+### console.warn([data][, ...])
 
 Same as `console.error`.
 
-## console.dir(obj[, options])
+### console.dir(obj[, options])
 
 Uses `util.inspect` on `obj` and prints resulting string to stdout. This function
 bypasses any custom `inspect()` function on `obj`. An optional *options* object
@@ -62,7 +72,7 @@ object. This is useful for inspecting large complicated objects. Defaults to
 - `colors` - if `true`, then the output will be styled with ANSI color codes.
 Defaults to `false`. Colors are customizable, see below.
 
-## console.time(label)
+### console.time(label)
 
 Used to calculate the duration of a specific operation. To start a timer, call
 the `console.time()` method, giving it a name as only parameter. To stop the
@@ -70,7 +80,7 @@ timer, and to get the elapsed time in milliseconds, just call the
 [`console.timeEnd()`](#console_console_timeend_label) method, again passing the
 timer's name as the parameter.
 
-## console.timeEnd(label)
+### console.timeEnd(label)
 
 Stops a timer that was previously started by calling
 [`console.time()`](#console_console_time_label) and print the result to the
@@ -85,15 +95,48 @@ Example:
     console.timeEnd('100-elements');
     // prints 100-elements: 262ms
 
-## console.trace(message[, ...])
+### console.trace(message[, ...])
 
 Print to stderr `'Trace :'`, followed by the formatted message and stack trace
 to the current position.
 
-## console.assert(value[, message][, ...])
+### console.assert(value[, message][, ...])
 
 Similar to [assert.ok()][], but the error message is formatted as
 `util.format(message...)`.
 
+## Class: Console
+
+<!--type=class-->
+
+Use `require('console').Console` or `console.Console` to access this class.
+
+    var Console = require('console').Console;
+    var Console = console.Console;
+
+You can use `Console` class to custom simple logger like `console`, but with
+different output streams.
+
+### new Console(stdout[, stderr])
+
+Create a new `Console` by passing one or two writable stream instances.
+`stdout` is a writable stream to print log or info output. `stderr`
+is used for warning or error output. If `stderr` isn't passed, the warning
+and error output will be sent to the `stdout`.
+
+    var output = fs.createWriteStream('./stdout.log');
+    var errorOutput = fs.createWriteStream('./stderr.log');
+    // custom simple logger
+    var logger = new Console(output, errorOutput);
+    // use it like console
+    var count = 5;
+    logger.log('count: %d', count);
+    // in stdout.log: count 5
+
+The global `console` is a special `Console` whose output is sent to
+`process.stdout` and `process.stderr`:
+
+    new Console(process.stdout, process.stderr);
+
 [assert.ok()]: assert.html#assert_assert_value_message_assert_ok_value_message
 [util.format()]: util.html#util_util_format_format