Fix PR comments and add jsdocs to getters, setters and get timers()

lib/internal/test_runner/mock/mock.js

@@ -28,7 +28,7 @@ const {
 } = require('internal/validators');
 const { MockTimers } = require('internal/test_runner/mock/mock_timers');
 
-function kDefaultFunction() { }
+function kDefaultFunction() {}
 
 class MockFunctionContext {
   #calls;
@@ -46,24 +46,24 @@ class MockFunctionContext {
   }
 
   /**
-   * Returns an array of all function calls.
-   * @returns {Array} An array containing all function calls.
+   * Gets an array of recorded calls made to the mock function.
+   * @returns {Array} An array of recorded calls.
    */
   get calls() {
     return ArrayPrototypeSlice(this.#calls, 0);
   }
 
   /**
-   * Retrieves the number of calls to the mock function.
-   * @returns {number} The number of calls.
+   * Retrieves the number of times the mock function has been called.
+   * @returns {number} The call count.
    */
   callCount() {
     return this.#calls.length;
   }
 
   /**
-   * Replaces the implementation of the function.
-   * @param {Function} implementation - The substitute function.
+   * Sets a new implementation for the mock function.
+   * @param {function} implementation - The new implementation for the mock function.
    */
   mockImplementation(implementation) {
     validateFunction(implementation, 'implementation');
@@ -72,7 +72,7 @@ class MockFunctionContext {
 
   /**
    * Replaces the implementation of the function only once.
-   * @param {Function} implementation - The substitute function.
+   * @param {function} implementation - The substitute function.
    * @param {number} [onCall] - The call index to be replaced.
    */
   mockImplementationOnce(implementation, onCall) {
@@ -84,7 +84,7 @@ class MockFunctionContext {
   }
 
   /**
-   * Discards all implementation mock changes.
+   * Restores the original function that was mocked.
    */
   restore() {
     const { descriptor, object, original, methodName } = this.#restore;
@@ -100,23 +100,23 @@ class MockFunctionContext {
   }
 
   /**
-   * Resets all function calls information.
+   * Resets the recorded calls to the mock function
    */
   resetCalls() {
     this.#calls = [];
   }
 
   /**
-   * Tracks the mock function call.
+   * Tracks a call made to the mock function.
    * @param {Object} call - The call details. 
    */
   trackCall(call) {
     ArrayPrototypePush(this.#calls, call);
   }
 
   /**
-   * Returns the next function implementation for the mock.
-   * @returns {Function} The next function implementation.
+   * Gets the next implementation to use for the mock function.
+   * @returns {Function} The next implementation.
    */
   nextImpl() {
     const nextCall = this.#calls.length;
@@ -140,20 +140,25 @@ class MockTracker {
   #mocks = [];
   #timers;
 
+  /**
+   * Returns the mock timers of this MockTracker instance.
+   * @returns {MockTimers} The mock timers instance.
+   */
   get timers() {
     this.#timers ??= new MockTimers();
     return this.#timers;
   }
 
   /**
-   * Creates a mock tracker of a function.
-   * @param {Function} [original] - The original function to be tracked.
-   * @param {Function} [implementation] - An optional function to replace the original function being tracked.
-   * @param {Object} [options]
-   * @returns {ProxyConstructor} The mock function.
+   * Creates a mock function tracker.
+   * @param {function} [original] - The original function to be tracked.
+   * @param {function} [implementation] - An optional replacement function for the original one.
+   * @param {Object} [options] - Additional tracking options.
+   * @param {number} [options.times=Infinity] - The maximum number of times the mock function can be called.
+   * @returns {ProxyConstructor} The mock function tracker.
    */
   fn(
-    original = function () { },
+    original = function () {},
     implementation = original,
     options = kEmptyObject,
   ) {
@@ -175,13 +180,17 @@ class MockTracker {
     return this.#setupMock(ctx, original);
   }
 
-  /**
-   * Creates a MockTracker on a specified method, that's part of an object or function.
-   * @param {(Object | Function)} objectOrFunction 
-   * @param {string} methodName
-   * @param {Function} [implementation] - An optional function to replace the original method being tracked.
-   * @param {*} options 
-   * @returns 
+ /**
+   * Creates a method tracker for a specified object or function.
+   *
+   * @param {(Object | Function)} objectOrFunction - The object or function containing the method to be tracked.
+   * @param {string} methodName - The name of the method to be tracked.
+   * @param {function} [implementation] - An optional replacement function for the original method.
+   * @param {Object} [options] - Additional tracking options.
+   * @param {boolean} [options.getter=false] - Indicates whether this is a getter method.
+   * @param {boolean} [options.setter=false] - Indicates whether this is a setter method.
+   * @param {number} [options.times=Infinity] - The maximum number of times the mock method can be called.
+   * @returns {ProxyConstructor} The mock method tracker.
    */
   method(
     objectOrFunction,
@@ -262,6 +271,14 @@ class MockTracker {
     return mock;
   }
 
+  /**
+   * Mocks a getter method of an object.
+   * @param {Object} object - The target object.
+   * @param {string} methodName - The name of the getter method to be mocked.
+   * @param {function} [implementation] - An optional replacement function for the targeted method.
+   * @param {Object} [options] - Additional tracking options.
+   * @returns {ProxyConstructor} The mock method tracker.
+   */
   getter(
     object,
     methodName,
@@ -290,6 +307,14 @@ class MockTracker {
     });
   }
 
+  /**
+   * Mocks a setter method of an object.
+   * @param {Object} object - The target object.
+   * @param {string} methodName  - The setter method to be mocked.
+   * @param {function} [implementation] - An optional replacement function for the targeted method.
+   * @param {Object} [options] - Additional tracking options.
+   * @returns {ProxyConstructor} The mock method tracker.
+   */
   setter(
     object,
     methodName,
@@ -319,7 +344,7 @@ class MockTracker {
   }
 
   /**
-   * Resets the mock tracker.
+   * Resets the mock tracker, restoring all mocks and clearing timers.
    */
   reset() {
     this.restoreAll();
@@ -328,7 +353,7 @@ class MockTracker {
   }
 
   /**
-   * Restore all mocks of this MockTracker.
+   * Restore all mocks created by this MockTracker instance.
    */
   restoreAll() {
     for (let i = 0; i < this.#mocks.length; i++) {