From a4f2f9ea8a2a0388c1d76838b90e87b623863868 Mon Sep 17 00:00:00 2001
From: Yazhong Liu <yorkiefixer@gmail.com>
Date: Wed, 7 May 2014 17:48:55 +0800
Subject: [PATCH] doc: add spec for util.deprecate()

Signed-off-by: Trevor Norris <trev.norris@gmail.com>
---
 doc/api/util.markdown | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/doc/api/util.markdown b/doc/api/util.markdown
index 2aab8c95c0..dc6c0f64ee 100644
--- 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.