doc: consolidate timers docs in timers.markdown

Rather than attempting to keep two versions of docs for timers up to
date, keep them in timers.markdown, and leave references to them in
globals.markdown.

Add setImmediate and clearImmediate to globals.markdown.

Change "To schedule" to "Schedules" in timers.markdown.

PR-URL: https://github.com/nodejs/node/pull/5837
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>
Reviewed-By: Claudio Rodriguez <cjrodr@yahoo.com>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>

doc/api/globals.markdown

@@ -50,19 +50,23 @@ console.log(__filename);
 
 `__filename` isn't actually a global but rather local to each module.
 
-## clearInterval(t)
+## clearImmediate(immediateObject)
 
-Stop a timer that was previously created with [`setInterval()`][]. The callback
+<!--type=global-->
-will not execute.
+
+[`clearImmediate`] is described in the [timers][] section.
+
+## clearInterval(intervalObject)
 
 <!--type=global-->
 
-The timer functions are global variables. See the [timers][] section.
+[`clearInterval`] is described in the [timers][] section.
 
-## clearTimeout(t)
+## clearTimeout(timeoutObject)
+
+<!--type=global-->
 
-Stop a timer that was previously created with [`setTimeout()`][]. The callback will
+[`clearTimeout`] is described in the [timers][] section.
-not execute.
 
 ## console
 
@@ -162,34 +166,33 @@ left untouched.
 Use the internal `require()` machinery to look up the location of a module,
 but rather than loading the module, just return the resolved filename.
 
-## setInterval(cb, ms)
+## setImmediate(callback[, arg][, ...])
 
-Run callback `cb` repeatedly every `ms` milliseconds. Note that the actual
+<!-- type=global -->
-interval may vary, depending on external factors like OS timer granularity and
+
-system load. It's never less than `ms` but it may be longer.
+[`setImmediate`] is described in the [timers][] section.
 
-The interval must be in the range of 1-2,147,483,647 inclusive. If the value is
+## setInterval(callback, delay[, arg][, ...])
-outside that range, it's changed to 1 millisecond. Broadly speaking, a timer
-cannot span more than 24.8 days.
 
-Returns an opaque value that represents the timer.
+<!-- type=global -->
 
-## setTimeout(cb, ms)
+[`setInterval`] is described in the [timers][] section.
 
-Run callback `cb` after *at least* `ms` milliseconds. The actual delay depends
+## setTimeout(callback, delay[, arg][, ...])
-on external factors like OS timer granularity and system load.
 
-The timeout must be in the range of 1-2,147,483,647 inclusive. If the value is
+<!-- type=global -->
-outside that range, it's changed to 1 millisecond. Broadly speaking, a timer
-cannot span more than 24.8 days.
 
-Returns an opaque value that represents the timer.
+[`setTimeout`] is described in the [timers][] section.
 
 [`console`]: console.html
 [`process` object]: process.html#process_process
-[`setInterval()`]: #globals_setinterval_cb_ms
-[`setTimeout()`]: #globals_settimeout_cb_ms
 [buffer section]: buffer.html
 [module system documentation]: modules.html
 [Modules]: modules.html#modules_modules
 [timers]: timers.html
+[`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

doc/api/timers.markdown

@@ -27,7 +27,7 @@ Returns the timer.
 
 ## setImmediate(callback[, arg][, ...])
 
-To schedule the "immediate" execution of `callback` after I/O events'
+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
@@ -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.
+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.
 
@@ -54,7 +54,7 @@ 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.
+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.