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

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) {