doc: minor improvements to util.md

PR-URL: https://github.com/nodejs/node/pull/6932
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Robert Jefe Lindstaedt <robert.lindstaedt@gmail.com>
Reviewed-By: Brian White <mscdex@mscdex.net>

1 files changed, 79 insertions, 77 deletions

diff --git a/doc/api/util.md b/doc/api/util.md
index 893d0de4eb..f1245993f0 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -19,12 +19,13 @@ const util = require('util');
 The `util.debuglog()` method is used to create a function that conditionally
 writes debug messages to `stderr` based on the existence of the `NODE_DEBUG`
 environment variable.  If the `section` name appears within the value of that
-environment variable, then the returned function operate similar to
+environment variable, then the returned function operates similar to
 `console.error()`.  If not, then the returned function is a no-op.
 
 For example:
 
 ```js
+const util = require('util');
 const debuglog = util.debuglog('foo');
 
 debuglog('hello from foo [%d]', 123);
@@ -46,7 +47,7 @@ environment variable. For example: `NODE_DEBUG=fs,net,tls`.
 ## util.deprecate(function, string)
 
 The `util.deprecate()` method wraps the given `function` in such a way that
-marks it as being deprecated.
+it is marked as deprecated.
 
 ```js
 const util = require('util');
@@ -58,10 +59,10 @@ exports.puts = util.deprecate(() => {
 }, 'util.puts: Use console.log instead');
 ```
 
-When called, `util.deprecated()` will return a function that will emit a
+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 that it is called. After the warning is emitted, the wrapped `function`
+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.
 
 If either the `--no-deprecation` or `--no-warnings` command line flags are
@@ -106,10 +107,10 @@ util.format('%s:%s', 'foo');
   // Returns 'foo:%s'
 ```
 
-If there are more arguments passed to the `util.format()` method than there are
-placeholders, the extra arguments are coerced into strings (for objects and
-symbols, `util.inspect()` is used) then concatenated to the returned string,
-delimited by a space.
+If there are more arguments passed to the `util.format()` method than the
+number of placeholders, the extra arguments are coerced into strings (for
+objects and symbols, `util.inspect()` is used) then concatenated to the
+returned string, each delimited by a space.
 
 ```js
 util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'
@@ -125,7 +126,7 @@ util.format(1, 2, 3); // '1 2 3'
 
 ## util.inherits(constructor, superConstructor)
 
-_Note: usage of util.inherits() is discouraged. Please use the ES6 `class` and
+_Note: usage of `util.inherits()` is discouraged. Please use the ES6 `class` and
 `extends` keywords to get language level inheritance support. Also note that
 the two styles are [semantically incompatible][]._
 
@@ -153,7 +154,7 @@ MyStream.prototype.write = function(data) {
     this.emit('data', data);
 }
 
-var stream = new MyStream();
+const stream = new MyStream();
 
 console.log(stream instanceof EventEmitter); // true
 console.log(MyStream.super_ === EventEmitter); // true
@@ -168,12 +169,11 @@ stream.write('It works!'); // Received data: "It works!"
 
 * `object` {any} Any JavaScript primitive or Object.
 * `options` {Object}
-  * `showHidden` {boolean} If `true`, the `object`'s non-enumerable and
-    symbol properties will be included in the formatted result. Defaults to
-    `false`.
-  * `depth` (number) Specifies how many times to recurse while formatting the
-    `object`. This is useful for inspecting large complicated objects. Defaults
-    to `2`. To make it recurse indefinitely pass `null`.
+  * `showHidden` {boolean} If `true`, the `object`'s non-enumerable symbols and
+    properties will be included in the formatted result. Defaults to `false`.
+  * `depth` {number} Specifies the number of times to recurse while formatting
+    the `object`. This is useful for inspecting large complicated objects.
+    Defaults to `2`. To make it recurse indefinitely pass `null`.
   * `colors` {boolean} If `true`, the output will be styled with ANSI color
     codes. Defaults to `false`. Colors are customizable, see
     [Customizing `util.inspect` colors][].
@@ -181,7 +181,7 @@ stream.write('It works!'); // Received data: "It works!"
     functions exported on the `object` being inspected will not be called.
     Defaults to `true`.
   * `showProxy` {boolean} If `true`, then objects and functions that are
-    `Proxy` objects will be introspected to show their `target` and `hander`
+    `Proxy` objects will be introspected to show their `target` and `handler`
     objects. Defaults to `false`.
   * `maxArrayLength` {number} Specifies the maximum number of array and
     `TypedArray` elements to include when formatting. Defaults to `100`. Set to
@@ -243,7 +243,7 @@ Objects may also define their own `inspect(depth, opts)` function that
 ```js
 const util = require('util');
 
-var obj = { name: 'nate' };
+const obj = { name: 'nate' };
 obj.inspect = function(depth) {
   return `{${this.name}}`;
 };
@@ -257,7 +257,9 @@ return a value of any type that will be formatted accordingly by
 `util.inspect()`.
 
 ```js
-var obj = { foo: 'this will not show up in the inspect() output' };
+const util = require('util');
+
+const obj = { foo: 'this will not show up in the inspect() output' };
 obj.inspect = function(depth) {
   return { bar: 'baz' };
 };
@@ -300,11 +302,11 @@ Returns `true` if the given `object` is an `Array`. Otherwise, returns `false`.
 ```js
 const util = require('util');
 
-util.isArray([])
+util.isArray([]);
   // true
-util.isArray(new Array)
+util.isArray(new Array);
   // true
-util.isArray({})
+util.isArray({});
   // false
 ```
 
@@ -319,11 +321,11 @@ Returns `true` if the given `object` is a `Boolean`. Otherwise, returns `false`.
 ```js
 const util = require('util');
 
-util.isBoolean(1)
+util.isBoolean(1);
   // false
-util.isBoolean(0)
+util.isBoolean(0);
   // false
-util.isBoolean(false)
+util.isBoolean(false);
   // true
 ```
 
@@ -338,11 +340,11 @@ Returns `true` if the given `object` is a `Buffer`. Otherwise, returns `false`.
 ```js
 const util = require('util');
 
-util.isBuffer({ length: 0 })
+util.isBuffer({ length: 0 });
   // false
-util.isBuffer([])
+util.isBuffer([]);
   // false
-util.isBuffer(Buffer.from('hello world'))
+util.isBuffer(Buffer.from('hello world'));
   // true
 ```
 
@@ -357,11 +359,11 @@ Returns `true` if the given `object` is a `Date`. Otherwise, returns `false`.
 ```js
 const util = require('util');
 
-util.isDate(new Date())
+util.isDate(new Date());
   // true
-util.isDate(Date())
+util.isDate(Date());
   // false (without 'new' returns a String)
-util.isDate({})
+util.isDate({});
   // false
 ```
 
@@ -377,11 +379,11 @@ Returns `true` if the given `object` is an [`Error`][]. Otherwise, returns
 ```js
 const util = require('util');
 
-util.isError(new Error())
+util.isError(new Error());
   // true
-util.isError(new TypeError())
+util.isError(new TypeError());
   // true
-util.isError({ name: 'Error', message: 'an error occurred' })
+util.isError({ name: 'Error', message: 'an error occurred' });
   // false
 ```
 
@@ -413,13 +415,13 @@ Returns `true` if the given `object` is a `Function`. Otherwise, returns
 const util = require('util');
 
 function Foo() {}
-var Bar = function() {};
+const Bar = function() {};
 
-util.isFunction({})
+util.isFunction({});
   // false
-util.isFunction(Foo)
+util.isFunction(Foo);
   // true
-util.isFunction(Bar)
+util.isFunction(Bar);
   // true
 ```
 
@@ -435,11 +437,11 @@ Returns `true` if the given `object` is strictly `null`. Otherwise, returns
 ```js
 const util = require('util');
 
-util.isNull(0)
+util.isNull(0);
   // false
-util.isNull(undefined)
+util.isNull(undefined);
   // false
-util.isNull(null)
+util.isNull(null);
   // true
 ```
 
@@ -455,11 +457,11 @@ returns `false`.
 ```js
 const util = require('util');
 
-util.isNullOrUndefined(0)
+util.isNullOrUndefined(0);
   // false
-util.isNullOrUndefined(undefined)
+util.isNullOrUndefined(undefined);
   // true
-util.isNullOrUndefined(null)
+util.isNullOrUndefined(null);
   // true
 ```
 
@@ -474,13 +476,13 @@ Returns `true` if the given `object` is a `Number`. Otherwise, returns `false`.
 ```js
 const util = require('util');
 
-util.isNumber(false)
+util.isNumber(false);
   // false
-util.isNumber(Infinity)
+util.isNumber(Infinity);
   // true
-util.isNumber(0)
+util.isNumber(0);
   // true
-util.isNumber(NaN)
+util.isNumber(NaN);
   // true
 ```
 
@@ -496,13 +498,13 @@ Returns `true` if the given `object` is strictly an `Object` __and__ not a
 ```js
 const util = require('util');
 
-util.isObject(5)
+util.isObject(5);
   // false
-util.isObject(null)
+util.isObject(null);
   // false
-util.isObject({})
+util.isObject({});
   // true
-util.isObject(function(){})
+util.isObject(function(){});
   // false
 ```
 
@@ -518,23 +520,23 @@ Returns `true` if the given `object` is a primitive type. Otherwise, returns
 ```js
 const util = require('util');
 
-util.isPrimitive(5)
+util.isPrimitive(5);
   // true
-util.isPrimitive('foo')
+util.isPrimitive('foo');
   // true
-util.isPrimitive(false)
+util.isPrimitive(false);
   // true
-util.isPrimitive(null)
+util.isPrimitive(null);
   // true
-util.isPrimitive(undefined)
+util.isPrimitive(undefined);
   // true
-util.isPrimitive({})
+util.isPrimitive({});
   // false
-util.isPrimitive(function() {})
+util.isPrimitive(function() {});
   // false
-util.isPrimitive(/^$/)
+util.isPrimitive(/^$/);
   // false
-util.isPrimitive(new Date())
+util.isPrimitive(new Date());
   // false
 ```
 
@@ -549,11 +551,11 @@ Returns `true` if the given `object` is a `RegExp`. Otherwise, returns `false`.
 ```js
 const util = require('util');
 
-util.isRegExp(/some regexp/)
+util.isRegExp(/some regexp/);
   // true
-util.isRegExp(new RegExp('another regexp'))
+util.isRegExp(new RegExp('another regexp'));
   // true
-util.isRegExp({})
+util.isRegExp({});
   // false
 ```
 
@@ -568,13 +570,13 @@ Returns `true` if the given `object` is a `string`. Otherwise, returns `false`.
 ```js
 const util = require('util');
 
-util.isString('')
+util.isString('');
   // true
-util.isString('foo')
+util.isString('foo');
   // true
-util.isString(String('foo'))
+util.isString(String('foo'));
   // true
-util.isString(5)
+util.isString(5);
   // false
 ```
 
@@ -589,11 +591,11 @@ Returns `true` if the given `object` is a `Symbol`. Otherwise, returns `false`.
 ```js
 const util = require('util');
 
-util.isSymbol(5)
+util.isSymbol(5);
   // false
-util.isSymbol('foo')
+util.isSymbol('foo');
   // false
-util.isSymbol(Symbol('foo'))
+util.isSymbol(Symbol('foo'));
   // true
 ```
 
@@ -608,12 +610,12 @@ Returns `true` if the given `object` is `undefined`. Otherwise, returns `false`.
 ```js
 const util = require('util');
 
-var foo;
-util.isUndefined(5)
+const foo = undefined;
+util.isUndefined(5);
   // false
-util.isUndefined(foo)
+util.isUndefined(foo);
   // true
-util.isUndefined(null)
+util.isUndefined(null);
   // false
 ```
 
@@ -627,7 +629,7 @@ The `util.log()` method prints the given `string` to `stdout` with an included
 timestamp.
 
 ```js
-const util = require('util')
+const util = require('util');
 
 util.log('Timestamped message.');
 ```