From 31e20c889e467aa4ba64b0b5baf602adc1359371 Mon Sep 17 00:00:00 2001 From: toasted-nutbread Date: Fri, 20 May 2022 10:28:38 -0400 Subject: ESlint JSdoc (#2148) * Install eslint-plugin-jsdoc * Initial rules setup * Update lists * Use @returns rather than @return * Remove error throwing code which is never executed * Fix issues relating to @throws * General error fixes * Update Display type documentation * Various doc fixes * Fix invalid tuple syntax * Doc updates * Remove unused * Doc updates * Enable jsdoc/require-returns * Update rules * Update remaining rules --- ext/js/dom/document-util.js | 16 +++++----- ext/js/dom/dom-text-scanner.js | 10 +++++-- ext/js/dom/sandbox/css-style-applier.js | 6 ++-- ext/js/dom/selector-observer.js | 52 +++++++++++++++++++++++---------- 4 files changed, 57 insertions(+), 27 deletions(-) (limited to 'ext/js/dom') diff --git a/ext/js/dom/document-util.js b/ext/js/dom/document-util.js index 10d91551..f5cf194b 100644 --- a/ext/js/dom/document-util.js +++ b/ext/js/dom/document-util.js @@ -68,27 +68,27 @@ class DocumentUtil { /** * Extract a sentence from a document. - * @param source The text source object, either `TextSourceRange` or `TextSourceElement`. - * @param layoutAwareScan Whether or not layout-aware scan mode should be used. - * @param extent The length of the sentence to extract. - * @param terminateAtNewlines Whether or not a sentence should be terminated at newline characters. - * @param terminatorMap A mapping of characters that terminate a sentence. + * @param {TextSourceRange|TextSourceElement} source The text source object, either `TextSourceRange` or `TextSourceElement`. + * @param {boolean} layoutAwareScan Whether or not layout-aware scan mode should be used. + * @param {number} extent The length of the sentence to extract. + * @param {boolean} terminateAtNewlines Whether or not a sentence should be terminated at newline characters. + * @param {Map} terminatorMap A mapping of characters that terminate a sentence. * Format: * ```js * new Map([ [character: string, [includeCharacterAtStart: boolean, includeCharacterAtEnd: boolean]], ... ]) * ``` - * @param forwardQuoteMap A mapping of quote characters that delimit a sentence. + * @param {Map} forwardQuoteMap A mapping of quote characters that delimit a sentence. * Format: * ```js * new Map([ [character: string, [otherCharacter: string, includeCharacterAtStart: boolean]], ... ]) * ``` - * @param backwardQuoteMap A mapping of quote characters that delimit a sentence, + * @param {Map} backwardQuoteMap A mapping of quote characters that delimit a sentence, * which is the inverse of forwardQuoteMap. * Format: * ```js * new Map([ [character: string, [otherCharacter: string, includeCharacterAtEnd: boolean]], ... ]) * ``` - * @returns The sentence and the offset to the original source: `{sentence: string, offset: integer}`. + * @returns {{sentence: string, offset: number}} The sentence and the offset to the original source. */ extractSentence(source, layoutAwareScan, extent, terminateAtNewlines, terminatorMap, forwardQuoteMap, backwardQuoteMap) { // Scan text diff --git a/ext/js/dom/dom-text-scanner.js b/ext/js/dom/dom-text-scanner.js index fff08825..83b16028 100644 --- a/ext/js/dom/dom-text-scanner.js +++ b/ext/js/dom/dom-text-scanner.js @@ -21,9 +21,12 @@ class DOMTextScanner { /** * Creates a new instance of a DOMTextScanner. - * @param node The DOM Node to start at. - * @param offset The character offset in to start at when node is a text node. + * @param {Node} node The DOM Node to start at. + * @param {number} offset The character offset in to start at when node is a text node. * Use 0 for non-text nodes. + * @param {boolean} forcePreserveWhitespace Whether or not whitespace should be forced to be preserved, + * regardless of CSS styling. + * @param {boolean} generateLayoutContent Whether or not newlines should be added based on CSS styling. */ constructor(node, offset, forcePreserveWhitespace=false, generateLayoutContent=true) { const ruby = DOMTextScanner.getParentRubyElement(node); @@ -393,6 +396,7 @@ class DOMTextScanner { /** * Gets seek information about an element. + * @param {Element} element The element to check. * @returns {{enterable: boolean, newlines: number}} The seek information. * The `enterable` value indicates whether the content of this node should be entered. * The `newlines` value corresponds to the number of newline characters that should be added. @@ -443,6 +447,8 @@ class DOMTextScanner { /** * Gets attributes for the specified character. * @param {string} character A string containing a single character. + * @param {boolean} preserveNewlines Whether or not newlines should be preserved. + * @param {boolean} preserveWhitespace Whether or not whitespace should be preserved. * @returns {number} An integer representing the attributes of the character. * 0: Character should be ignored. * 1: Character is collapsible whitespace. diff --git a/ext/js/dom/sandbox/css-style-applier.js b/ext/js/dom/sandbox/css-style-applier.js index a6938d92..6c45f13e 100644 --- a/ext/js/dom/sandbox/css-style-applier.js +++ b/ext/js/dom/sandbox/css-style-applier.js @@ -36,8 +36,9 @@ class CssStyleApplier { /** * Creates a new instance of the class. - * @param styleDataUrl The local URL to the JSON file continaing the style rules. + * @param {string} styleDataUrl The local URL to the JSON file continaing the style rules. * The style rules should be of the format: + * ``` * [ * { * selectors: [(selector:string)...], @@ -46,6 +47,7 @@ class CssStyleApplier { * ] * }... * ] + * ``` */ constructor(styleDataUrl) { this._styleDataUrl = styleDataUrl; @@ -84,7 +86,7 @@ class CssStyleApplier { /** * Applies CSS styles directly to the "style" attribute using the "class" attribute. * This only works for elements with a single class. - * @param elements An iterable collection of HTMLElement objects. + * @param {Iterable} elements An iterable collection of HTMLElement objects. */ applyClassStyles(elements) { const elementStyles = []; diff --git a/ext/js/dom/selector-observer.js b/ext/js/dom/selector-observer.js index c2065103..071c3971 100644 --- a/ext/js/dom/selector-observer.js +++ b/ext/js/dom/selector-observer.js @@ -19,19 +19,41 @@ * Class which is used to observe elements matching a selector in specific element. */ class SelectorObserver { + /** + * @function OnAddedCallback + * @param {Element} element The element which was added. + * @returns {*} Custom data which is assigned to element and passed to callbacks. + */ + + /** + * @function OnRemovedCallback + * @param {Element} element The element which was removed. + * @param {*} data The custom data corresponding to the element. + */ + + /** + * @function OnChildrenUpdatedCallback + * @param {Element} element The element which had its children updated. + * @param {*} data The custom data corresponding to the element. + */ + + /** + * @function IsStaleCallback + * @param {Element} element The element which had its children updated. + * @param {*} data The custom data corresponding to the element. + * @returns {boolean} Whether or not the data is stale for the element. + */ + /** * Creates a new instance. - * @param selector A string CSS selector used to find elements. - * @param ignoreSelector A string CSS selector used to filter elements, or null for no filtering. - * @param onAdded A function which is invoked for each element that is added that matches the selector. - * The signature is (element) => data. - * @param onRemoved A function which is invoked for each element that is removed, or null. - * The signature is (element, data) => void. - * @param onChildrenUpdated A function which is invoked for each element which has its children updated, or null. - * The signature is (element, data) => void. - * @param isStale A function which checks if the data is stale for a given element, or null. + * @param {object} details The configuration for the object. + * @param {string} details.selector A string CSS selector used to find elements. + * @param {?string} details.ignoreSelector A string CSS selector used to filter elements, or `null` for no filtering. + * @param {OnAddedCallback} details.onAdded A function which is invoked for each element that is added that matches the selector. + * @param {?OnRemovedCallback} details.onRemoved A function which is invoked for each element that is removed, or `null`. + * @param {?OnChildrenUpdatedCallback} details.onChildrenUpdated A function which is invoked for each element which has its children updated, or `null`. + * @param {?IsStaleCallback} details.isStale A function which checks if the data is stale for a given element, or `null`. * If the element is stale, it will be removed and potentially re-added. - * The signature is (element, data) => bool. */ constructor({selector, ignoreSelector=null, onAdded=null, onRemoved=null, onChildrenUpdated=null, isStale=null}) { this._selector = selector; @@ -49,7 +71,7 @@ class SelectorObserver { /** * Returns whether or not an element is currently being observed. - * @returns True if an element is being observed, false otherwise. + * @returns {boolean} `true` if an element is being observed, `false` otherwise. */ get isObserving() { return this._observingElement !== null; @@ -57,10 +79,10 @@ class SelectorObserver { /** * Starts DOM mutation observing the target element. - * @param element The element to observe changes in. - * @param attributes A boolean for whether or not attribute changes should be observed. - * @throws An error if element is null. - * @throws An error if an element is already being observed. + * @param {Element} element The element to observe changes in. + * @param {boolean} [attributes] A boolean for whether or not attribute changes should be observed. + * @throws {Error} An error if element is null. + * @throws {Error} An error if an element is already being observed. */ observe(element, attributes=false) { if (element === null) { -- cgit v1.2.3