feat(minor): improve code documentation

.eslintrc.json

@@ -7,7 +7,8 @@
     },
     "ignorePatterns": ["/dist", "/docs-site"],
     "extends": [
-        "eslint:recommended"
+        "eslint:recommended",
+        "plugin:jsdoc/recommended"
     ],
     "globals": {
         "Atomics": "readonly",
@@ -24,21 +25,31 @@
         "files": ["**.ts"],
         "extends": [
             "eslint:recommended",
-            "plugin:@typescript-eslint/recommended"
+            "plugin:@typescript-eslint/recommended",
+            "plugin:jsdoc/recommended-typescript"
         ],
         "parser": "@typescript-eslint/parser",
         "plugins": [
             "@typescript-eslint",
             "import",
-            "node"
+            "node",
+            "jsdoc"
         ],
         "rules": {
             "@typescript-eslint/explicit-module-boundary-types": ["off"],
             "@typescript-eslint/ban-ts-comment": ["off"],
             "@typescript-eslint/no-explicit-any": ["off"],
             "semi": ["off"],
             "@typescript-eslint/semi": ["warn", "always"],
-            "@typescript-eslint/no-inferrable-types": ["off"]
+            "@typescript-eslint/no-inferrable-types": ["off"],
+            "jsdoc/require-param": ["off"],
+            "jsdoc/check-param-names": ["warn", {
+                "checkDestructured": false
+            }],
+            "jsdoc/require-returns": ["off"],
+            "jsdoc/require-jsdoc": ["off"],
+            "jsdoc/require-yields": ["off"],
+            "jsdoc/require-param-description": ["off"]
         }
     }, {
         "files": ["test/**/**.ts"],
@@ -49,11 +60,15 @@
     "plugins": [
         "@typescript-eslint",
         "import",
-        "node"
+        "node",
+        "jsdoc"
     ],
     "settings": {
         "import/parsers": {
             "@typescript-eslint/parser": [".ts"]
+        },
+        "jsdoc": {
+            "exemptDestructuredRootsFromChecks": true
         }
     },
     "rules": {
@@ -108,13 +123,6 @@
         }],
         "no-eval": ["error"],
         "array-callback-return": ["error"],
-        "valid-jsdoc": ["error", {
-            "requireParamType": true,
-            "requireReturnType": true,
-            "requireReturn": false,
-            "requireParamDescription": false,
-            "requireReturnDescription": false
-        }],
         "no-empty": ["error", {
             "allowEmptyCatch": true
         }],

package.json

@@ -61,6 +61,7 @@
     "@vitest/coverage-v8": "^0.34.6",
     "eslint": "^8.46.0",
     "eslint-plugin-import": "^2.28.0",
+    "eslint-plugin-jsdoc": "^46.9.0",
     "eslint-plugin-node": "github:giladgd/eslint-plugin-node#dev/giladgd/fixImportExtentionFixingInTypeScript",
     "husky": "^8.0.3",
     "rimraf": "^5.0.1",

src/AsyncDisposeAggregator.ts

@@ -26,10 +26,8 @@ import {DisposedError} from "./DisposedError.js";
  * ```
  */
 export class AsyncDisposeAggregator {
-    /** @internal */
-    private readonly _targets: AsyncDisposeAggregatorTarget[] = [];
-    /** @internal */
-    private _disposed: boolean = false;
+    /** @internal */ private readonly _targets: AsyncDisposeAggregatorTarget[] = [];
+    /** @internal */ private _disposed: boolean = false;
 
     public constructor() {
         this.add = this.add.bind(this);
@@ -40,14 +38,6 @@ export class AsyncDisposeAggregator {
     /**
      * Adds a target to be disposed.
      * You can wrap the target with a `WeakRef` to prevent this class from holding a strong reference to the target.
-     * @param {(function(): void) | ({dispose: (function(): void)}) | ({Symbol.dispose: (function(): void)}) |
-     *  ({Symbol.asyncDispose: (function(): void)}) |
-     *  Promise<
-     *      (function(): void) | ({dispose: (function(): void)}) | ({Symbol.dispose: (function(): void)}) |
-     *      ({Symbol.asyncDispose: (function(): void)})
-     *      >
-     * } target
-     * @returns {this}
      */
     public add(target: AsyncDisposeAggregatorTarget): this {
         this._ensureNotDisposed();
@@ -58,7 +48,6 @@ export class AsyncDisposeAggregator {
 
     /**
      * Disposes all the targets that have been added and clears the list of targets.
-     * @returns {Promise<void>}
      */
     public async dispose(): Promise<void> {
         this._ensureNotDisposed();
@@ -113,9 +102,9 @@ export class AsyncDisposeAggregator {
     }
 }
 
-type AsyncDisposeAggregatorTarget = DisposeTarget | Promise<DisposeTarget>;
+export type AsyncDisposeAggregatorTarget = AsyncDisposeAggregatorWrappedTarget | Promise<AsyncDisposeAggregatorWrappedTarget>;
 
-type DisposeTarget = (() => void | Promise<void>) | {
+export type AsyncDisposeAggregatorWrappedTarget = (() => void | Promise<void>) | {
     [Symbol.asyncDispose](): void | Promise<void>
 } | {
     [Symbol.dispose](): void

src/DisposeAggregator.ts

@@ -20,10 +20,8 @@ import {DisposedError} from "./DisposedError.js";
  * ```
  */
 export class DisposeAggregator {
-    /** @internal */
-    private readonly _targets: DisposeAggregatorTarget[] = [];
-    /** @internal */
-    private _disposed: boolean = false;
+    /** @internal */ private readonly _targets: DisposeAggregatorTarget[] = [];
+    /** @internal */ private _disposed: boolean = false;
 
     public constructor() {
         this.add = this.add.bind(this);
@@ -34,8 +32,6 @@ export class DisposeAggregator {
     /**
      * Adds a target to be disposed.
      * You can wrap the target with a `WeakRef` to prevent this class from holding a strong reference to the target.
-     * @param {(function(): void) | ({dispose: (function(): void)}) | ({Symbol.dispose: (function(): void)})} target
-     * @returns {this}
      */
     public add<T extends DisposeAggregatorTarget>(target: T): T {
         this._ensureNotDisposed();
@@ -84,7 +80,7 @@ export class DisposeAggregator {
     }
 }
 
-type DisposeAggregatorTarget = (() => void) | {
+export type DisposeAggregatorTarget = (() => void) | {
     [Symbol.dispose](): void
 } | {
     dispose(): void

src/EventRelay.ts

@@ -28,14 +28,10 @@ import {DisposedError} from "./DisposedError.js";
  * Something happened: eat a cookie
  * Done notifying listeners
  * ```
- * @template T
- * @class EventRelay
  */
 export class EventRelay<T> {
-    /** @internal */
-    private readonly _listenerCallbacks: Map<((data: T) => void), Set<EventRelayListenerHandle>>;
-    /** @internal */
-    private _disposed: boolean = false;
+    /** @internal */ private readonly _listenerCallbacks: Map<((data: T) => void), Set<EventRelayListenerHandle>>;
+    /** @internal */ private _disposed: boolean = false;
 
     public constructor() {
         this._listenerCallbacks = new Map<((data: T) => void), Set<EventRelayListenerHandle>>();
@@ -152,11 +148,7 @@ export class EventRelayListenerHandle {
         return this._dispose == null;
     }
 
-    /**
-     * @internal
-     * @param {function(): void} dispose
-     * @returns {EventRelayListenerHandle}
-     */
+    /** @internal */
     public static _create(dispose: () => void) {
         return new EventRelayListenerHandle(dispose);
     }

src/LongTimeout.ts

@@ -18,14 +18,10 @@ const maxTimeoutDelay = 2147483647;
  * ```
  */
 export class LongTimeout {
-    /** @internal */
-    private readonly _callback: () => void;
-    /** @internal */
-    private readonly _startTime: number;
-    /** @internal */
-    private readonly _delay: number;
-    /** @internal */
-    private _timeout: ReturnType<typeof setTimeout> | undefined;
+    /** @internal */ private readonly _callback: () => void;
+    /** @internal */ private readonly _startTime: number;
+    /** @internal */ private readonly _delay: number;
+    /** @internal */ private _timeout: ReturnType<typeof setTimeout> | undefined;
 
     public constructor(callback: () => void, delay: number) {
         this._callback = callback;
@@ -83,9 +79,6 @@ export class LongTimeout {
  * // to clear the timeout, call clearLongTimeout
  * // clearLongTimeout(timeout);
  * ```
- * @param {function(): void} callback
- * @param {number} delay
- * @returns {LongTimeout}
  */
 export function setLongTimeout(callback: () => void, delay: number): LongTimeout {
     return new LongTimeout(callback, delay);
@@ -111,7 +104,6 @@ export function setLongTimeout(callback: () => void, delay: number): LongTimeout
  * clearLongTimeout(timeout);
  * clearLongTimeout(timeout2);
  * ```
- * @param {LongTimeout | number | undefined | null} timeout
  */
 export function clearLongTimeout(timeout: LongTimeout | number | undefined | null | ReturnType<typeof setTimeout>) {
     if (timeout == null)