From f755e6786b95a80989bbbdd25889728324dce84c Mon Sep 17 00:00:00 2001
From: Erick Wendel <erick.workspace@gmail.com>
Date: Tue, 5 Sep 2023 13:53:07 -0300
Subject: [PATCH] test_runner: add jsdocs to MockTimers

Signed-off-by: Erick Wendel <erick.workspace@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/49476
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>
---
 lib/internal/test_runner/mock/mock_timers.js | 24 ++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/lib/internal/test_runner/mock/mock_timers.js b/lib/internal/test_runner/mock/mock_timers.js
index 7e38f9f7b5113c..1624b03f8af674 100644
--- a/lib/internal/test_runner/mock/mock_timers.js
+++ b/lib/internal/test_runner/mock/mock_timers.js
@@ -455,6 +455,13 @@ class MockTimers {
     );
   }
 
+  /**
+   * Advances the virtual time of MockTimers by the specified duration (in milliseconds).
+   * This method simulates the passage of time and triggers any scheduled timers that are due.
+   * @param {number} [time=1] - The amount of time (in milliseconds) to advance the virtual time.
+   * @throws {ERR_INVALID_STATE} If MockTimers are not enabled.
+   * @throws {ERR_INVALID_ARG_VALUE} If a negative time value is provided.
+   */
   tick(time = 1) {
     if (!this.#isEnabled) {
       throw new ERR_INVALID_STATE(
@@ -488,6 +495,12 @@ class MockTimers {
     }
   }
 
+  /**
+   * Enables MockTimers for the specified timers.
+   * @param {string[]} timers - An array of timer types to enable, e.g., ['setTimeout', 'setInterval'].
+   * @throws {ERR_INVALID_STATE} If MockTimers are already enabled.
+   * @throws {ERR_INVALID_ARG_VALUE} If an unsupported timer type is specified.
+   */
   enable(timers = SUPPORTED_TIMERS) {
     if (this.#isEnabled) {
       throw new ERR_INVALID_STATE(
@@ -513,10 +526,17 @@ class MockTimers {
     this.#toggleEnableTimers(true);
   }
 
+  /**
+   * An alias for `this.reset()`, allowing the disposal of the `MockTimers` instance.
+   */
   [SymbolDispose]() {
     this.reset();
   }
 
+  /**
+   * Resets MockTimers, disabling any enabled timers and clearing the execution queue.
+   * Does nothing if MockTimers are not enabled.
+   */
   reset() {
     // Ignore if not enabled
     if (!this.#isEnabled) return;
@@ -531,6 +551,10 @@ class MockTimers {
     }
   }
 
+  /**
+   * Runs all scheduled timers until there are no more pending timers.
+   * @throws {ERR_INVALID_STATE} If MockTimers are not enabled.
+   */
   runAll() {
     if (!this.#isEnabled) {
       throw new ERR_INVALID_STATE(