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

1 files changed, 37 insertions, 15 deletions

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