doc: add spec for util.deprecate()

Signed-off-by: Trevor Norris <trev.norris@gmail.com>

diff --git a/doc/api/util.markdown b/doc/api/util.markdown
index 2aab8c9..dc6c0f6 100644 (file)
--- a/doc/api/util.markdown
+++ b/doc/api/util.markdown
@@ -257,6 +257,21 @@ through the `constructor.super_` property.
     stream.write("It works!"); // Received data: "It works!"
 
 
+## util.deprecate(function, string)
+
+Marks that a method should not be used any more.
+
+    exports.puts = exports.deprecate(function() {
+      for (var i = 0, len = arguments.length; i < len; ++i) {
+        process.stdout.write(arguments[i] + '\n');
+      }
+    }, 'util.puts: Use console.log instead')
+
+It returns a modified function which warns once by default. If
+`--no-deprecation` is set then this function is a NO-OP. If
+`--throw-deprecation` is set then the application will throw an exception
+if the deprecated API is used.
+
 ## util.debug(string)
 
     Stability: 0 - Deprecated: use console.error() instead.