typings: add JSDoc typings for timers

Added JSDoc typings for the `timers` lib module.

PR-URL: #38834
Reviewed-By: Anatoli Papirovski <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>

lib/timers.js

@@ -127,10 +127,16 @@ function enroll(item, msecs) {
 }
 
 
-/*
- * DOM-style timers
+/**
+ * Schedules the execution of a one-time `callback`
+ * after `after` milliseconds.
+ * @param {Function} callback
+ * @param {number} [after]
+ * @param {any} [arg1]
+ * @param {any} [arg2]
+ * @param {any} [arg3]
+ * @returns {Timeout}
  */
-
 function setTimeout(callback, after, arg1, arg2, arg3) {
   validateCallback(callback);
 
@@ -170,6 +176,11 @@ ObjectDefineProperty(setTimeout, customPromisify, {
   }
 });
 
+/**
+ * Cancels a timeout.
+ * @param {Timeout | string | number} timer
+ * @returns {void}
+ */
 function clearTimeout(timer) {
   if (timer && timer._onTimeout) {
     timer._onTimeout = null;
@@ -185,6 +196,16 @@ function clearTimeout(timer) {
   }
 }
 
+/**
+ * Schedules repeated execution of `callback`
+ * every `repeat` milliseconds.
+ * @param {Function} callback
+ * @param {number} [repeat]
+ * @param {any} [arg1]
+ * @param {any} [arg2]
+ * @param {any} [arg3]
+ * @returns {Timeout}
+ */
 function setInterval(callback, repeat, arg1, arg2, arg3) {
   validateCallback(callback);
 
@@ -215,6 +236,11 @@ function setInterval(callback, repeat, arg1, arg2, arg3) {
   return timeout;
 }
 
+/**
+ * Cancels an interval.
+ * @param {Timeout | string | number} timer
+ * @returns {void}
+ */
 function clearInterval(timer) {
   // clearTimeout and clearInterval can be used to clear timers created from
   // both setTimeout and setInterval, as specified by HTML Living Standard:
@@ -227,6 +253,10 @@ Timeout.prototype.close = function() {
   return this;
 };
 
+/**
+ * Coerces a `Timeout` to a primitive.
+ * @returns {number}
+ */
 Timeout.prototype[SymbolToPrimitive] = function() {
   const id = this[async_id_symbol];
   if (!this[kHasPrimitive]) {
@@ -236,6 +266,15 @@ Timeout.prototype[SymbolToPrimitive] = function() {
   return id;
 };
 
+/**
+ * Schedules the immediate execution of `callback`
+ * after I/O events' callbacks.
+ * @param {Function} callback
+ * @param {any} [arg1]
+ * @param {any} [arg2]
+ * @param {any} [arg3]
+ * @returns {Immediate}
+ */
 function setImmediate(callback, arg1, arg2, arg3) {
   validateCallback(callback);
 
@@ -271,7 +310,11 @@ ObjectDefineProperty(setImmediate, customPromisify, {
   }
 });
 
-
+/**
+ * Cancels an immediate.
+ * @param {Immediate} immediate
+ * @returns {void}
+ */
 function clearImmediate(immediate) {
   if (!immediate || immediate._destroyed)
     return;