From 328178066aab21a45f4a7f7c4fa0022452ace2ed Mon Sep 17 00:00:00 2001 From: Bryan English Date: Fri, 18 Mar 2016 13:00:20 -0700 Subject: [PATCH 1/2] 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). --- doc/api/timers.markdown | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/doc/api/timers.markdown b/doc/api/timers.markdown index 7e4efb47c12929..c0f10135eae361 100644 --- a/doc/api/timers.markdown +++ b/doc/api/timers.markdown @@ -7,15 +7,15 @@ 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() @@ -27,10 +27,10 @@ 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`][]. Optionally you can also pass arguments 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 @@ -42,7 +42,7 @@ If `callback` is not a function `setImmediate()` will throw immediately. ## setInterval(callback, delay[, arg][, ...]) To schedule the repeated execution of `callback` every `delay` milliseconds. -Returns a `intervalObject` for possible use with `clearInterval()`. Optionally +Returns a `intervalObject` for possible use with [`clearInterval`][]. Optionally you can also pass arguments to the callback. To follow browser behavior, when using delays larger than 2147483647 @@ -54,8 +54,8 @@ If `callback` is not a function `setInterval()` will throw immediately. ## 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`][]. Optionally +you can also pass arguments 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, @@ -76,11 +76,15 @@ 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 +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. 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 From cc2d91932ac95fa67baa73ea8199d5e141302a68 Mon Sep 17 00:00:00 2001 From: Bryan English Date: Fri, 18 Mar 2016 13:53:42 -0700 Subject: [PATCH 2/2] doc: remove "you" from timers doc --- doc/api/timers.markdown | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/doc/api/timers.markdown b/doc/api/timers.markdown index c0f10135eae361..56c41e2de35d93 100644 --- a/doc/api/timers.markdown +++ b/doc/api/timers.markdown @@ -19,7 +19,7 @@ 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. @@ -30,11 +30,12 @@ Returns the timer. 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`][]. Optionally you can also pass arguments to the callback. +[`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. If `callback` is not a function `setImmediate()` will throw immediately. @@ -42,8 +43,8 @@ If `callback` is not a function `setImmediate()` will throw immediately. ## 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 @@ -54,8 +55,8 @@ If `callback` is not a function `setInterval()` will throw immediately. ## 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, @@ -71,14 +72,14 @@ If `callback` is not a function `setTimeout()` will throw immediately. ## 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.