doc: general improvements to timers.md

Overall improvements to timers.md documentation,

Includes squashed commit from @bengl:

  doc: add timer classes

  The timers returned by `setTimeout` and friends are
  actually instances of `Timeout` and `Immediate`.
  Documenting them as such, so that the `ref` and
  `unref` methods can be identified as methods on
  `Timeout` objects.

  Sparked by discussion in #5792

Author: jasnell

doc/api/globals.md

@@ -208,7 +208,7 @@ but rather than loading the module, just return the resolved filename.
 [native addons]: addons.html
 [timers]: timers.html
 [`clearImmediate`]: timers.html#timers_clearimmediate_immediateobject
-[`clearInterval`]: timers.html#timers_clearinterval_intervalobject
+[`clearInterval`]: timers.html#timers_clearinterval_immediateobject
 [`clearTimeout`]: timers.html#timers_cleartimeout_timeoutobject
 [`setImmediate`]: timers.html#timers_setimmediate_callback_arg
 [`setInterval`]: timers.html#timers_setinterval_callback_delay_arg

doc/api/timers.md

@@ -2,90 +2,148 @@
 
     Stability: 3 - Locked
 
-All of the timer functions are globals.  You do not need to `require()`
-this module in order to use them.
+The `timer` module exposes a global API for scheduling functions to
+be called at some future period of time. Because the timer functions are
+globals, there is no need to call `require('timers')` to use the API.
 
-## clearImmediate(immediateObject)
+The timer functions within Node.js implement a similar API as the timers API
+provided by Web Browsers but use a different internal implementation that is
+built around [the Node.js Event Loop][].
 
-Stops an `immediateObject`, as created by [`setImmediate`][], from triggering.
+## Class: Immediate
 
-## clearInterval(intervalObject)
+This object is created internally and is returned from [`setImmediate()`][]. It
+can be passed to [`clearImmediate()`][] in order to cancel the scheduled
+actions.
 
-Stops an `intervalObject`, as created by [`setInterval`][], from triggering.
+## Class: Timeout
 
-## clearTimeout(timeoutObject)
+This object is created internally and is returned from [`setTimeout()`][] and
+[`setInterval()`][]. It can be passed to [`clearTimeout`][] or
+[`clearInterval()`][] (respectively) in order to cancel the scheduled actions.
 
-Prevents a `timeoutObject`, as created by [`setTimeout`][], from triggering.
+By default, when a timer is scheduled using either [`setTimeout`] or
+[`setInterval()`][], the Node.js event loop will continue running as long as the
+timer is active. Each of the `Timeout` objects returned by these functions
+export both `timeout.ref()` and `timeout.unref()` functions that can be used to
+control this default behavior.
 
-## ref()
+### timeout.ref()
 
-If a timer was previously `unref()`d, then `ref()` can be called to explicitly
-request the timer hold the program open. If the timer is already `ref`d calling
-`ref` again will have no effect.
+When called, requests that the Node.js event loop *not* exit so long as the
+`Timeout` is active. Calling `timeout.ref()` multiple times will have no effect.
 
-Returns the timer.
+*Note*: By default, all `Timeout` objects are "ref'd", making it normally
+unnecessary to call `timeout.ref()` unless `timeout.unref()` had been called
+previously.
 
-## setImmediate(callback[, arg][, ...])
+Returns a reference to the `Timeout`.
 
-Schedules "immediate" execution of `callback` after I/O events'
-callbacks and before timers set by [`setTimeout`][] and [`setInterval`][] are
-triggered. Returns an `immediateObject` for possible use with
-[`clearImmediate`][]. Additional optional arguments may be passed to the
-callback.
+### timeout.unref()
 
-Callbacks for immediates are queued in the order in which they were created.
-The entire callback queue is processed every event loop iteration. If an
-immediate is queued from inside an executing callback, that immediate won't fire
-until the next event loop iteration.
+When called, the active `Timeout` object will not require the Node.js event loop
+to remain active. If there is no other activity keeping the event loop running,
+the process may exit before the `Timeout` object's callback is invoked. Calling
+`timout.unref()` multiple times will have no effect.
 
-If `callback` is not a function `setImmediate()` will throw immediately.
+*Note*: Calling `timout.unref()` creates an internal timer that will wake the
+Node.js event loop. Creating too many of these can adversely impact performance
+of the Node.js application.
 
-## setInterval(callback, delay[, arg][, ...])
+Returns a reference to the `Timeout`.
+
+## Scheduling Timers
+
+A timer in Node.js is an internal construct that calls a given function after
+a certain period of time. When a timer's function is called varies depending on
+which method was used to create the timer and what other work the Node.js
+event loop is doing.
+
+### setImmediate(callback[, ...arg])
+
+* `callback` {Function} The function to call at the end of this turn of
+  [the Node.js Event Loop]
+* `[, ...arg]` Optional arguments to pass when the `callback` is called.
+
+Schedules the "immediate" execution of the `callback` after I/O events'
+callbacks and before timers created using [`setTimeout()`][] and
+[`setInterval()`][] are triggered. Returns an `Immediate` for use with
+[`clearImmediate()`][].
+
+When multiple calls to `setImmediate()` are made, the `callback` functions are
+queued for execution in the order in which they are created. The entire callback
+queue is processed every event loop iteration. If an immediate timer is queued
+from inside an executing callback, that timer will not be triggered until the
+next event loop iteration.
+
+If `callback` is not a function, a [`TypeError`][] will be thrown.
+
+### setInterval(callback, delay[, ...arg])
+
+* `callback` {Function} The function to call when the timer elapses.
+* `delay` {number} The number of milliseconds to wait before calling the
+  `callback`.
+* `[, ...arg]` Optional arguments to pass when the `callback` is called.
 
 Schedules repeated execution of `callback` every `delay` milliseconds.
-Returns a `intervalObject` for possible use with [`clearInterval`][]. Additional
-optional arguments may be passed to the callback.
+Returns a `Timeout` for use with [`clearInterval()`][].
 
-To follow browser behavior, when using delays larger than 2147483647
-milliseconds (approximately 25 days) or less than 1, Node.js will use 1 as the
-`delay`.
+When `delay` is larger than `2147483647` or less than `1`, the `delay` will be
+set to `1`.
 
-If `callback` is not a function `setInterval()` will throw immediately.
+If `callback` is not a function, a [`TypeError`][] will be thrown.
 
-## setTimeout(callback, delay[, arg][, ...])
+### setTimeout(callback, delay[, ...arg])
+
+* `callback` {Function} The function to call when the timer elapses.
+* `delay` {number} The number of milliseconds to wait before calling the
+  `callback`.
+* `[, ...arg]` Optional arguments to pass when the `callback` is called.
 
 Schedules execution of a one-time `callback` after `delay` milliseconds.
-Returns a `timeoutObject` for possible use with [`clearTimeout`][]. Additional
-optional arguments may be passed to the callback.
+Returns a `Timeout` for use with [`clearTimeout()`][].
 
-The callback will likely not be invoked in precisely `delay` milliseconds.
+The `callback` will likely not be invoked in precisely `delay` milliseconds.
 Node.js makes no guarantees about the exact timing of when callbacks will fire,
 nor of their ordering. The callback will be called as close as possible to the
 time specified.
 
-To follow browser behavior, when using delays larger than 2147483647
-milliseconds (approximately 25 days) or less than 1, the timeout is executed
-immediately, as if the `delay` was set to 1.
+*Note*: When `delay` is larger than `2147483647` or less than `1`, the `delay`
+will be set to `1`.
+
+If `callback` is not a function, a [`TypeError`][] will be thrown.
+
+## Cancelling Timers
+
+The [`setImmediate()`][], [`setInterval()`][], and [`setTimeout()`][] methods
+each return objects that represent the scheduled timers. These can be used to
+cancel the timer and prevent it from triggering.
+
+### clearImmediate(immediate)
+
+* `immediate` {Immediate} An `Immediate` object as returned by
+  [`setImmediate()`][].
+
+Cancels an `Immediate` object created by [`setImmediate()`][].
+
+### clearInterval(timeout)
+
+* `timeout` {Timeout} A `Timeout` object as returned by [`setInterval()`][].
 
-If `callback` is not a function `setTimeout()` will throw immediately.
+Cancels a `Timeout` object created by [`setInterval()`][].
 
-## unref()
+### clearTimeout(timeout)
 
-The opaque value returned by [`setTimeout`][] and [`setInterval`][] also has the
-method `timer.unref()` which allows the creation of a timer that is active but
-if it is the only item left in the event loop, it won't keep the program
-running. If the timer is already `unref`d calling `unref` again will have no
-effect.
+* `timeout` {Timeout} A `Timeout` object as returned by [`setTimeout()`][].
 
-In the case of [`setTimeout`][], `unref` creates a separate timer that will
-wakeup the event loop, creating too many of these may adversely effect event
-loop performance -- use wisely.
+Cancels a `Timeout` object created by [`setTimeout()`][].
 
-Returns the timer.
 
-[`clearImmediate`]: timers.html#timers_clearimmediate_immediateobject
-[`clearInterval`]: timers.html#timers_clearinterval_intervalobject
-[`clearTimeout`]: timers.html#timers_cleartimeout_timeoutobject
-[`setImmediate`]: timers.html#timers_setimmediate_callback_arg
-[`setInterval`]: timers.html#timers_setinterval_callback_delay_arg
-[`setTimeout`]: timers.html#timers_settimeout_callback_delay_arg
+[the Node.js Event Loop]: https://github.com/nodejs/node/blob/master/doc/topics/the-event-loop-timers-and-nexttick.md
+[`TypeError`]: errors.html#errors_class_typerror
+[`clearImmediate()`]: timers.html#timers_clearimmediate_immediate
+[`clearInterval()`]: timers.html#timers_clearinterval_timeout
+[`clearTimeout()`]: timers.html#timers_cleartimeout_timeout
+[`setImmediate()`]: timers.html#timers_setimmediate_callback_arg
+[`setInterval()`]: timers.html#timers_setinterval_callback_delay_arg
+[`setTimeout()`]: timers.html#timers_settimeout_callback_delay_arg