From 29673b8ac876558a438e1f7e1fccfea211666d71 Mon Sep 17 00:00:00 2001
From: Voltrex <62040526+VoltrexMaster@users.noreply.github.com>
Date: Sat, 29 May 2021 01:08:48 +0430
Subject: [PATCH] typings: add JSDoc typings for timers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Added JSDoc typings for the `timers` lib module.

PR-URL: https://github.com/nodejs/node/pull/38834
Reviewed-By: Anatoli Papirovski <apapirovski@mac.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>
---
 lib/timers.js | 51 +++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 47 insertions(+), 4 deletions(-)

diff --git a/lib/timers.js b/lib/timers.js
index 485f577d29f2f0..a4543fea1df6bc 100644
--- a/lib/timers.js
+++ b/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;