summaryrefslogtreecommitdiff
path: root/ext/js/dom
diff options
context:
space:
mode:
authortoasted-nutbread <toasted-nutbread@users.noreply.github.com>2022-05-20 10:28:38 -0400
committerGitHub <noreply@github.com>2022-05-20 10:28:38 -0400
commit31e20c889e467aa4ba64b0b5baf602adc1359371 (patch)
treea033db935a817b2d407ec20843176610a87a6e16 /ext/js/dom
parentae0ad227c0fd293609a21e5cc1d2a4b85fe7c520 (diff)
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
Diffstat (limited to 'ext/js/dom')
-rw-r--r--ext/js/dom/document-util.js16
-rw-r--r--ext/js/dom/dom-text-scanner.js10
-rw-r--r--ext/js/dom/sandbox/css-style-applier.js6
-rw-r--r--ext/js/dom/selector-observer.js52
4 files changed, 57 insertions, 27 deletions
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<string, *[]>} 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<string, *[]>} 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<string, *[]>} 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<HTMLElement>} 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
@@ -20,18 +20,40 @@
*/
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) {