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: #16393
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>

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