Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: grammar, clarity and links in timers doc #5792

Closed
wants to merge 2 commits into from
Closed

doc: grammar, clarity and links in timers doc #5792

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3281780
doc: grammar, clarity and links in timers doc
bengl Mar 18, 2016
cc2d919
doc: remove "you" from timers doc
bengl Mar 18, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 16 additions & 12 deletions doc/api/timers.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will also technically clear a regular timeout, I forget if the opposite is true, but the difference is really Immediates vs Timeouts, intervals are just a timeout with an extra property.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, just confirmed, clearTimeout() does also work on intervals.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is that worth documenting? I don't think I want to encourage folks to clear a timeout with clearInterval or vice-versa.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The actual objects are, for reference and naming, Timeout and Immediate.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bengl I would refer to them by the names above, maybe call interval a "repeating Timeout", or "Interval (Timeout)"?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmmm, turns out Immediates actually have a constructor name and Timeouts do not, call timeouts and intervals whatever you want I guess, Immediate should probably be Immediate, though.


## clearTimeout(timeoutObject)

Prevents a timeout from triggering.
Prevents a `timeoutObject`, as created by [`setTimeout`][], from triggering.

## ref()

Expand All @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Instead of using you here... perhaps: Additional optional arguments may be passed to the callback. or something similar.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd prefer to eliminate the use of the you pronoun in general (I see it's used several places in this doc)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sure! That was in there previously, but now's as good a time as any to fix that.


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
Expand All @@ -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
Expand All @@ -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,
Expand All @@ -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