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

3 files changed, 41 insertions, 38 deletions

diff --git a/ext/js/general/cache-map.js b/ext/js/general/cache-map.js
index f993cc26..fccb7cdd 100644
--- a/ext/js/general/cache-map.js
+++ b/ext/js/general/cache-map.js
@@ -21,7 +21,7 @@
 class CacheMap {
     /**
      * Creates a new CacheMap.
-     * @param maxSize The maximum number of entries able to be stored in the cache.
+     * @param {number} maxSize The maximum number of entries able to be stored in the cache.
      */
     constructor(maxSize) {
         if (!(
@@ -42,6 +42,7 @@ class CacheMap {
 
     /**
      * Returns the number of items in the cache.
+     * @type {number}
      */
     get size() {
         return this._map.size;
@@ -49,6 +50,7 @@ class CacheMap {
 
     /**
      * Returns the maximum number of items that can be added to the cache.
+     * @type {number}
      */
     get maxSize() {
         return this._maxSize;
@@ -56,8 +58,8 @@ class CacheMap {
 
     /**
      * Returns whether or not an element exists at the given key.
-     * @param key The key of the element.
-     * @returns `true` if an element with the specified key exists, `false` otherwise.
+     * @param {*} key The key of the element.
+     * @returns {boolean} `true` if an element with the specified key exists, `false` otherwise.
      */
     has(key) {
         return this._map.has(key);
@@ -65,8 +67,8 @@ class CacheMap {
 
     /**
      * Gets an element at the given key, if it exists. Otherwise, returns undefined.
-     * @param key The key of the element.
-     * @returns The existing value at the key, if any; `undefined` otherwise.
+     * @param {*} key The key of the element.
+     * @returns {*} The existing value at the key, if any; `undefined` otherwise.
      */
     get(key) {
         const node = this._map.get(key);
@@ -77,8 +79,8 @@ class CacheMap {
 
     /**
      * Sets a value at a given key.
-     * @param key The key of the element.
-     * @param value The value to store in the cache.
+     * @param {*} key The key of the element.
+     * @param {*} value The value to store in the cache.
      */
     set(key, value) {
         let node = this._map.get(key);
diff --git a/ext/js/general/object-property-accessor.js b/ext/js/general/object-property-accessor.js
index 516ad72f..ea410ac3 100644
--- a/ext/js/general/object-property-accessor.js
+++ b/ext/js/general/object-property-accessor.js
@@ -21,8 +21,7 @@
 class ObjectPropertyAccessor {
     /**
      * Create a new accessor for a specific object.
-     * @param target The object which the getter and mutation methods are applied to.
-     * @returns A new ObjectPropertyAccessor instance.
+     * @param {object} target The object which the getter and mutation methods are applied to.
      */
     constructor(target) {
         this._target = target;
@@ -30,11 +29,11 @@ class ObjectPropertyAccessor {
 
     /**
      * Gets the value at the specified path.
-     * @param pathArray The path to the property on the target object.
-     * @param pathLength How many parts of the pathArray to use.
+     * @param {(string|number)[]} pathArray The path to the property on the target object.
+     * @param {number} [pathLength] How many parts of the pathArray to use.
      *   This parameter is optional and defaults to the length of pathArray.
-     * @returns The value found at the path.
-     * @throws An error is thrown if pathArray is not valid for the target object.
+     * @returns {*} The value found at the path.
+     * @throws {Error} An error is thrown if pathArray is not valid for the target object.
      */
     get(pathArray, pathLength) {
         let target = this._target;
@@ -51,9 +50,9 @@ class ObjectPropertyAccessor {
 
     /**
      * Sets the value at the specified path.
-     * @param pathArray The path to the property on the target object.
-     * @param value The value to assign to the property.
-     * @throws An error is thrown if pathArray is not valid for the target object.
+     * @param {(string|number)[]} pathArray The path to the property on the target object.
+     * @param {*} value The value to assign to the property.
+     * @throws {Error} An error is thrown if pathArray is not valid for the target object.
      */
     set(pathArray, value) {
         const ii = pathArray.length - 1;
@@ -70,8 +69,8 @@ class ObjectPropertyAccessor {
 
     /**
      * Deletes the property of the target object at the specified path.
-     * @param pathArray The path to the property on the target object.
-     * @throws An error is thrown if pathArray is not valid for the target object.
+     * @param {(string|number)[]}pathArray The path to the property on the target object.
+     * @throws {Error} An error is thrown if pathArray is not valid for the target object.
      */
     delete(pathArray) {
         const ii = pathArray.length - 1;
@@ -92,8 +91,8 @@ class ObjectPropertyAccessor {
 
     /**
      * Swaps two properties of an object or array.
-     * @param pathArray1 The path to the first property on the target object.
-     * @param pathArray2 The path to the second property on the target object.
+     * @param {(string|number)[]} pathArray1 The path to the first property on the target object.
+     * @param {(string|number)[]} pathArray2 The path to the second property on the target object.
      * @throws An error is thrown if pathArray1 or pathArray2 is not valid for the target object,
      *   or if the swap cannot be performed.
      */
@@ -129,8 +128,9 @@ class ObjectPropertyAccessor {
 
     /**
      * Converts a path string to a path array.
-     * @param pathArray The path array to convert.
-     * @returns A string representation of pathArray.
+     * @param {(string|number)[]} pathArray The path array to convert.
+     * @returns {string} A string representation of `pathArray`.
+     * @throws {Error} An error is thrown if any item of `pathArray` is not a string or an integer.
      */
     static getPathString(pathArray) {
         const regexShort = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
@@ -166,8 +166,9 @@ class ObjectPropertyAccessor {
     /**
      * Converts a path array to a path string. For the most part, the format of this string
      * matches Javascript's notation for property access.
-     * @param pathString The path string to convert.
-     * @returns An array representation of pathString.
+     * @param {string} pathString The path string to convert.
+     * @returns {(string | number)[]} An array representation of `pathString`.
+     * @throws {Error} An error is thrown if `pathString` is malformed.
      */
     static getPathArray(pathString) {
         const pathArray = [];
@@ -286,11 +287,11 @@ class ObjectPropertyAccessor {
 
     /**
      * Checks whether an object or array has the specified property.
-     * @param object The object to test.
-     * @param property The property to check for existence.
+     * @param {*} object The object to test.
+     * @param {string|number} property The property to check for existence.
      *   This value should be a string if the object is a non-array object.
      *   For arrays, it should be an integer.
-     * @returns true if the property exists, otherwise false.
+     * @returns {boolean} `true` if the property exists, otherwise `false`.
      */
     static hasProperty(object, property) {
         switch (typeof property) {
@@ -315,9 +316,9 @@ class ObjectPropertyAccessor {
 
     /**
      * Checks whether a property is valid for the given object
-     * @param object The object to test.
-     * @param property The property to check for existence.
-     * @returns true if the property is correct for the given object type, otherwise false.
+     * @param {object} object The object to test.
+     * @param {string|number} property The property to check for existence.
+     * @returns {boolean} `true` if the property is correct for the given object type, otherwise `false`.
      *   For arrays, this means that the property should be a positive integer.
      *   For non-array objects, the property should be a string.
      */
diff --git a/ext/js/general/regex-util.js b/ext/js/general/regex-util.js
index d74a2f1e..6fa1a220 100644
--- a/ext/js/general/regex-util.js
+++ b/ext/js/general/regex-util.js
@@ -22,12 +22,12 @@ class RegexUtil {
     /**
      * Applies string.replace using a regular expression and replacement string as arguments.
      * A source map of the changes is also maintained.
-     * @param text A string of the text to replace.
-     * @param sourceMap An instance of `TextSourceMap` which corresponds to `text`.
-     * @param pattern A regular expression to use as the replacement.
-     * @param replacement A replacement string that follows the format of the standard
+     * @param {string} text A string of the text to replace.
+     * @param {TextSourceMap} sourceMap An instance of `TextSourceMap` which corresponds to `text`.
+     * @param {RegExp} pattern A regular expression to use as the replacement.
+     * @param {string} replacement A replacement string that follows the format of the standard
      *   JavaScript regular expression replacement string.
-     * @return A new string with the pattern replacements applied and the source map updated.
+     * @returns {string} A new string with the pattern replacements applied and the source map updated.
      */
     static applyTextReplacement(text, sourceMap, pattern, replacement) {
         const isGlobal = pattern.global;
@@ -57,10 +57,10 @@ class RegexUtil {
 
     /**
      * Applies the replacement string for a given regular expression match.
-     * @param replacement The replacement string that follows the format of the standard
+     * @param {string} replacement The replacement string that follows the format of the standard
      *   JavaScript regular expression replacement string.
-     * @param match A match object returned from RegExp.match.
-     * @return A new string with the pattern replacement applied.
+     * @param {object} match A match object returned from RegExp.match.
+     * @returns {string} A new string with the pattern replacement applied.
      */
     static applyMatchReplacement(replacement, match) {
         const pattern = this._matchReplacementPattern;