Add JSDoc comments to various utility functions and core files.

This change adds JSDoc-style comments to several functions and classes across the codebase to improve readability and maintainability.

Comments were added to:
- `src/SEQTA.ts`: Explained the `init()` function.
- `src/seqta/utils/waitForElm.ts`: Detailed the `waitForElm()` function, its parameters, and behavior.
- `src/seqta/utils/stringToHTML.ts`: Clarified the `stringToHTML()` function, including its sanitization and styling features.
- `src/seqta/utils/delay.ts`: Added a brief explanation for the `delay()` utility.
- `src/seqta/utils/mutex.ts`: Documented the `Mutex` class and its `acquire` method (renamed from `lock`), explaining its asynchronous locking mechanism and the role of the returned unlock function.
This commit is contained in:
google-labs-jules[bot]
2025-05-29 12:19:57 +00:00
parent fc4b121d30
commit 074e73b0fd
5 changed files with 92 additions and 5 deletions
+14
View File
@@ -1,6 +1,20 @@
import { eventManager } from "@/seqta/utils/listeners/EventManager";
import { delay } from "@/seqta/utils/delay";
/**
* Asynchronously waits for an element to be present in the DOM.
*
* This function can use either a polling mechanism (via `setTimeout`) or
* a `MutationObserver` (via `eventManager.register`) to detect the element.
* By default, it uses the `eventManager` which is more efficient.
*
* @param {string} selector The CSS selector for the target element.
* @param {boolean} [usePolling=false] If true, forces the use of `setTimeout` for polling.
* @param {number} [interval=100] The polling interval in milliseconds (only applicable if `usePolling` is true).
* @param {number} [maxIterations] Optional. The maximum number of polling attempts before rejecting (only applicable if `usePolling` is true).
* @returns {Promise<Element>} A Promise that resolves with the found DOM Element.
* If `usePolling` is true and `maxIterations` is reached, the Promise rejects with an Error.
*/
export async function waitForElm(
selector: string,
usePolling: boolean = false,