doc: grammar, clarity and links in timers doc

Added appropriate in-document links. Clarified a bit of
`setImmediate`, including a quick grammar fix (plural possessive
apostrophe).

PR-URL: https://github.com/nodejs/node/pull/5792
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

diff --git a/doc/api/timers.markdown b/doc/api/timers.markdown
index cf2f24a..7859e7f 100644 (file)
--- a/doc/api/timers.markdown
+++ b/doc/api/timers.markdown
@@ -7,19 +7,19 @@ this module in order to use them.
 
 ## clearImmediate(immediateObject)
 
-Stops an immediate from triggering.
+Stops an `immediateObject`, as created by [`setImmediate`][], from triggering.
 
 ## clearInterval(intervalObject)
 
-Stops an interval from triggering.
+Stops an `intervalObject`, as created by [`setInterval`][], from triggering.
 
 ## clearTimeout(timeoutObject)
 
-Prevents a timeout from triggering.
+Prevents a `timeoutObject`, as created by [`setTimeout`][], from triggering.
 
 ## ref()
 
-If you had previously `unref()`d a timer you can call `ref()` to explicitly
+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.
 
@@ -27,21 +27,22 @@ Returns the timer.
 
 ## setImmediate(callback[, arg][, ...])
 
-To schedule the "immediate" execution of `callback` after I/O events
-callbacks and before [`setTimeout`][] and [`setInterval`][]. Returns an
-`immediateObject` for possible use with `clearImmediate()`. Optionally you
-can also pass arguments to the callback.
+To schedule the "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.
 
 Callbacks for immediates are queued in the order in which they were created.
-The entire callback queue is processed every event loop iteration. If you queue
-an immediate from inside an executing callback, that immediate won't fire
+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.
 
 ## setInterval(callback, delay[, arg][, ...])
 
 To schedule the repeated execution of `callback` every `delay` milliseconds.
-Returns a `intervalObject` for possible use with `clearInterval()`. Optionally
-you can also pass arguments to the callback.
+Returns a `intervalObject` for possible use with [`clearInterval`][]. Additional
+optional arguments may be passed to the callback.
 
 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
@@ -50,8 +51,8 @@ milliseconds (approximately 25 days) or less than 1, Node.js will use 1 as the
 ## setTimeout(callback, delay[, arg][, ...])
 
 To schedule execution of a one-time `callback` after `delay` milliseconds.
-Returns a `timeoutObject` for possible use with `clearTimeout()`. Optionally you
-can also pass arguments to the callback.
+Returns a `timeoutObject` for possible use with [`clearTimeout`][]. Additional
+optional arguments may be passed to the callback.
 
 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,
@@ -65,16 +66,20 @@ immediately, as if the `delay` was set to 1.
 ## unref()
 
 The opaque value returned by [`setTimeout`][] and [`setInterval`][] also has the
-method `timer.unref()` which will allow you to create a timer that is active but
+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.
 
-In the case of `setTimeout` when you `unref` you create a separate timer that
-will wakeup the event loop, creating too many of these may adversely effect
-event loop performance -- use wisely.
+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.
 
 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