From f53cc37578b453d072e760fb82e53becc5829e86 Mon Sep 17 00:00:00 2001 From: Bryan English Date: Fri, 18 Mar 2016 13:00:20 -0700 Subject: [PATCH] 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 Reviewed-By: Benjamin Gruenbaum --- doc/api/timers.markdown | 41 +++++++++++++++++++++++------------------ 1 file changed, 23 insertions(+), 18 deletions(-) diff --git a/doc/api/timers.markdown b/doc/api/timers.markdown index cf2f24ae938adb..7859e7fecd6273 100644 --- 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