doc: unify and dedupe returned values in timers.md

PR-URL: #20310
Reviewed-By: Ruben Bridgewater <[email protected]>
Reviewed-By: Trivikram Kamat <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Tiancheng "Timothy" Gu <[email protected]>

doc/api/timers.md

@@ -28,7 +28,7 @@ functions that can be used to control this default behavior.
 added: v9.7.0
 -->
 
-* Returns: {Immediate}
+* Returns: {Immediate} a reference to `immediate`
 
 When called, requests that the Node.js event loop *not* exit so long as the
 `Immediate` is active. Calling `immediate.ref()` multiple times will have no
@@ -37,22 +37,18 @@ effect.
 By default, all `Immediate` objects are "ref'ed", making it normally unnecessary
 to call `immediate.ref()` unless `immediate.unref()` had been called previously.
 
-Returns a reference to the `Immediate`.
-
 ### immediate.unref()
 <!-- YAML
 added: v9.7.0
 -->
 
-* Returns: {Immediate}
+* Returns: {Immediate} a reference to `immediate`
 
 When called, the active `Immediate` object will not require the Node.js event
 loop to remain active. If there is no other activity keeping the event loop
 running, the process may exit before the `Immediate` object's callback is
 invoked. Calling `immediate.unref()` multiple times will have no effect.
 
-Returns a reference to the `Immediate`.
-
 ## Class: Timeout
 
 This object is created internally and is returned from [`setTimeout()`][] and
@@ -70,22 +66,20 @@ control this default behavior.
 added: v0.9.1
 -->
 
-* Returns: {Timeout}
+* Returns: {Timeout} a reference to `timeout`
 
 When called, requests that the Node.js event loop *not* exit so long as the
 `Timeout` is active. Calling `timeout.ref()` multiple times will have no effect.
 
 By default, all `Timeout` objects are "ref'ed", making it normally unnecessary
 to call `timeout.ref()` unless `timeout.unref()` had been called previously.
 
-Returns a reference to the `Timeout`.
-
 ### timeout.unref()
 <!-- YAML
 added: v0.9.1
 -->
 
-* Returns: {Timeout}
+* Returns: {Timeout} a reference to `timeout`
 
 When called, the active `Timeout` object will not require the Node.js event loop
 to remain active. If there is no other activity keeping the event loop running,
@@ -96,8 +90,6 @@ Calling `timeout.unref()` creates an internal timer that will wake the Node.js
 event loop. Creating too many of these can adversely impact performance
 of the Node.js application.
 
-Returns a reference to the `Timeout`.
-
 ## Scheduling Timers
 
 A timer in Node.js is an internal construct that calls a given function after
@@ -113,9 +105,10 @@ added: v0.9.1
 * `callback` {Function} The function to call at the end of this turn of
   [the Node.js Event Loop]
 * `...args` {any} Optional arguments to pass when the `callback` is called.
+* Returns: {Immediate} for use with [`clearImmediate()`][]
 
 Schedules the "immediate" execution of the `callback` after I/O events'
-callbacks. Returns an `Immediate` for use with [`clearImmediate()`][].
+callbacks.
 
 When multiple calls to `setImmediate()` are made, the `callback` functions are
 queued for execution in the order in which they are created. The entire callback
@@ -155,10 +148,9 @@ added: v0.0.1
 * `delay` {number} The number of milliseconds to wait before calling the
   `callback`.
 * `...args` {any} Optional arguments to pass when the `callback` is called.
-* Returns: {Timeout}
+* Returns: {Timeout} for use with [`clearInterval()`][]
 
 Schedules repeated execution of `callback` every `delay` milliseconds.
-Returns a `Timeout` for use with [`clearInterval()`][].
 
 When `delay` is larger than `2147483647` or less than `1`, the `delay` will be
 set to `1`.
@@ -174,10 +166,9 @@ added: v0.0.1
 * `delay` {number} The number of milliseconds to wait before calling the
   `callback`.
 * `...args` {any} Optional arguments to pass when the `callback` is called.
-* Returns: {Timeout}
+* Returns: {Timeout} for use with [`clearTimeout()`][]
 
 Schedules execution of a one-time `callback` after `delay` milliseconds.
-Returns a `Timeout` for use with [`clearTimeout()`][].
 
 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,