util: Add debuglog, deprecate console lookalikes

1 files changed, 75 insertions, 36 deletions

diff --git a/doc/api/util.markdown b/doc/api/util.markdown
index 8b34ba6658..a1bfdb0f69 100644
--- a/doc/api/util.markdown
+++ b/doc/api/util.markdown
@@ -2,9 +2,46 @@
 
     Stability: 5 - Locked
 
-These functions are in the module `'util'`. Use `require('util')` to access
-them.
+These functions are in the module `'util'`. Use `require('util')` to
+access them.
 
+The `util` module is primarily designed to support the needs of Node's
+internal APIs.  Many of these utilities are useful for your own
+programs.  If you find that these functions are lacking for your
+purposes, however, you are encouraged to write your own utilities.  We
+are not interested in any future additions to the `util` module that
+are unnecessary for Node's internal functionality.
+
+## util.debuglog(section)
+
+* `section` {String} The section of the program to be debugged
+* Returns: {Function} The logging function
+
+This is used to create a function which conditionally writes to stderr
+based on the existence of a `NODE_DEBUG` environment variable.  If the
+`section` name appears in that environment variable, then the returned
+function will be similar to `console.error()`.  If not, then the
+returned function is a no-op.
+
+For example:
+
+```javascript
+var debuglog = util.debuglog('foo');
+
+var bar = 123;
+debuglog('hello from foo [%d]', bar);
+```
+
+If this program is run with `NODE_DEBUG=foo` in the environment, then
+it will output something like:
+
+    FOO 3245: hello from foo [123]
+
+where `3245` is the process id.  If it is not run with that
+environment variable set, then it will not print anything.
+
+You may separate multiple `NODE_DEBUG` environment variables with a
+comma.  For example, `NODE_DEBUG=fs,net,tls`.
 
 ## util.format(format, [...])
 
@@ -37,35 +74,12 @@ Each argument is converted to a string with `util.inspect()`.
     util.format(1, 2, 3); // '1 2 3'
 
 
-## util.debug(string)
-
-A synchronous output function. Will block the process and
-output `string` immediately to `stderr`.
-
-    require('util').debug('message on stderr');
-
-## util.error([...])
-
-Same as `util.debug()` except this will output all arguments immediately to
-`stderr`.
-
-## util.puts([...])
-
-A synchronous output function. Will block the process and output all arguments
-to `stdout` with newlines after each argument.
-
-## util.print([...])
-
-A synchronous output function. Will block the process, cast each argument to a
-string then output to `stdout`. Does not place newlines after each argument.
-
 ## util.log(string)
 
 Output with timestamp on `stdout`.
 
     require('util').log('Timestamped message.');
 
-
 ## util.inspect(object, [options])
 
 Return a string representation of `object`, which is useful for debugging.
@@ -94,6 +108,8 @@ Example of inspecting all properties of the `util` object:
 
 ### Customizing `util.inspect` colors
 
+<!-- type=misc -->
+
 Color output (if enabled) of `util.inspect` is customizable globally
 via `util.inspect.styles` and `util.inspect.colors` objects.
 
@@ -116,6 +132,8 @@ There are also `bold`, `italic`, `underline` and `inverse` codes.
 
 ### Custom `inspect()` function on Objects
 
+<!-- type=misc -->
+
 Objects also may define their own `inspect(depth)` function which `util.inspect()`
 will invoke and use the result of when inspecting the object:
 
@@ -198,17 +216,6 @@ Returns `true` if the given "object" is an `Error`. `false` otherwise.
       // false
 
 
-## util.pump(readableStream, writableStream, [callback])
-
-    Stability: 0 - Deprecated: Use readableStream.pipe(writableStream)
-
-Read the data from `readableStream` and send it to the `writableStream`.
-When `writableStream.write(data)` returns `false` `readableStream` will be
-paused until the `drain` event occurs on the `writableStream`. `callback` gets
-an error as its only argument and is called when `writableStream` is closed or
-when an error occurs.
-
-
 ## util.inherits(constructor, superConstructor)
 
 Inherit the prototype methods from one
@@ -241,3 +248,35 @@ through the `constructor.super_` property.
         console.log('Received data: "' + data + '"');
     })
     stream.write("It works!"); // Received data: "It works!"
+
+
+## util.debug(string)
+
+    Stability: 0 - Deprecated: use console.error() instead.
+
+Deprecated predecessor of `console.error`.
+
+## util.error([...])
+
+    Stability: 0 - Deprecated: Use console.error() instead.
+
+Deprecated predecessor of `console.error`.
+
+## util.puts([...])
+
+    Stability: 0 - Deprecated: Use console.log() instead.
+
+Deprecated predecessor of `console.log`.
+
+## util.print([...])
+
+    Stability: 0 - Deprecated: Use `console.log` instead.
+
+Deprecated predecessor of `console.log`.
+
+
+## util.pump(readableStream, writableStream, [callback])
+
+    Stability: 0 - Deprecated: Use readableStream.pipe(writableStream)
+
+Deprecated predecessor of `stream.pipe()`.