diff options
author | Rich Trott <rtrott@gmail.com> | 2017-10-22 14:23:57 -0700 |
---|---|---|
committer | Rich Trott <rtrott@gmail.com> | 2017-11-16 22:00:16 -0800 |
commit | ccc87ebb3393a7a4738ed20d9378857633e74c76 (patch) | |
tree | 6f20e5ab73012470c87eddaa63c5068f6b995291 /doc | |
parent | 60698c245596ac50cd4d672059ec2e47090b102c (diff) | |
download | android-node-v8-ccc87ebb3393a7a4738ed20d9378857633e74c76.tar.gz android-node-v8-ccc87ebb3393a7a4738ed20d9378857633e74c76.tar.bz2 android-node-v8-ccc87ebb3393a7a4738ed20d9378857633e74c76.zip |
doc: improve documentation for util.deprecate()
Improve documentation for `util.deprecate()`. In particular, provide
complete function signature, document arguments, and document return
value.
PR-URL: https://github.com/nodejs/node/pull/16393
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/api/util.md | 21 |
1 files changed, 14 insertions, 7 deletions
diff --git a/doc/api/util.md b/doc/api/util.md index 3ba8cade54..e100971af9 100644 --- a/doc/api/util.md +++ b/doc/api/util.md @@ -107,13 +107,20 @@ environment variable set, then it will not print anything. Multiple comma-separated `section` names may be specified in the `NODE_DEBUG` environment variable. For example: `NODE_DEBUG=fs,net,tls`. -## util.deprecate(function, string) +## util.deprecate(fn, msg[, code]) <!-- YAML added: v0.8.0 --> -The `util.deprecate()` method wraps the given `function` or class in such a way that -it is marked as deprecated. +* `fn` {Function} The function that is being deprecated. +* `msg` {string} A warning message to display when the deprecated function is + invoked. +* `code` {string} A deprecation code. See the [list of deprecated APIs][] for a + list of codes. +* Returns: {Function} The deprecated function wrapped to emit a warning. + +The `util.deprecate()` method wraps `fn` (which may be a function or class) in +such a way that it is marked as deprecated. <!-- eslint-disable prefer-rest-params --> ```js @@ -127,10 +134,9 @@ exports.puts = util.deprecate(function() { ``` When called, `util.deprecate()` will return a function that will emit a -`DeprecationWarning` using the `process.on('warning')` event. By default, -this warning will be emitted and printed to `stderr` exactly once, the first -time it is called. After the warning is emitted, the wrapped `function` -is called. +`DeprecationWarning` using the `process.on('warning')` event. The warning will +be emitted and printed to `stderr` exactly once, the first time it is called. +After the warning is emitted, the wrapped function is called. If either the `--no-deprecation` or `--no-warnings` command line flags are used, or if the `process.noDeprecation` property is set to `true` *prior* to @@ -1213,4 +1219,5 @@ Deprecated predecessor of `console.log`. [Internationalization]: intl.html [WHATWG Encoding Standard]: https://encoding.spec.whatwg.org/ [constructor]: https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/constructor +[list of deprecated APIS]: deprecations.html#deprecations_list_of_deprecated_apis [semantically incompatible]: https://github.com/nodejs/node/issues/4179 |