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, 10 insertions, 9 deletions

diff --git a/ext/js/app/popup-window.js b/ext/js/app/popup-window.js
index 6a63a9cb..19753906 100644
--- a/ext/js/app/popup-window.js
+++ b/ext/js/app/popup-window.js
@@ -21,7 +21,7 @@
 class PopupWindow extends EventDispatcher {
     /**
      * Creates a new instance.
-     * @param {object} details
+     * @param {object} details Details about how to set up the instance.
      * @param {string} details.id The ID of the popup.
      * @param {number} details.depth The depth of the popup.
      * @param {number} details.frameId The ID of the host frame.
@@ -53,10 +53,10 @@ class PopupWindow extends EventDispatcher {
     /**
      * The parent of the popup, which is always `null` for `PopupWindow` instances,
      * since any potential parent popups are in a different frame.
-     * @param {Popup} value
-     * @type {Popup}
+     * @param {Popup} _value The parent to assign.
+     * @throws {Error} Throws an error, since this class doesn't support children.
      */
-    set parent(value) {
+    set parent(_value) {
         throw new Error('Not supported on PopupWindow');
     }
 
@@ -71,10 +71,10 @@ class PopupWindow extends EventDispatcher {
 
     /**
      * Attempts to set the child popup.
-     * @param {Popup} value
+     * @param {Popup} _value The child to assign.
      * @throws Throws an error, since this class doesn't support children.
      */
-    set child(value) {
+    set child(_value) {
         throw new Error('Not supported on PopupWindow');
     }
 
@@ -168,7 +168,7 @@ class PopupWindow extends EventDispatcher {
 
     /**
      * Shows and updates the positioning and content of the popup.
-     * @param {Popup.ContentDetails} details Settings for the outer popup.
+     * @param {Popup.ContentDetails} _details Settings for the outer popup.
      * @param {Display.ContentDetails} displayDetails The details parameter passed to `Display.setContent`.
      * @returns {Promise<void>}
      */
@@ -180,6 +180,7 @@ class PopupWindow extends EventDispatcher {
     /**
      * Sets the custom styles for the popup content.
      * @param {string} css The CSS rules.
+     * @returns {Promise<void>}
      */
     setCustomCss(css) {
         return this._invoke(false, 'Display.setCustomCss', {id: this._id, css});
@@ -187,6 +188,7 @@ class PopupWindow extends EventDispatcher {
 
     /**
      * Stops the audio auto-play timer, if one has started.
+     * @returns {Promise<void>}
      */
     clearAutoPlayTimer() {
         return this._invoke(false, 'Display.clearAutoPlayTimer', {id: this._id});
@@ -194,7 +196,7 @@ class PopupWindow extends EventDispatcher {
 
     /**
      * Sets the scaling factor of the popup content.
-     * @param {number} scale The scaling factor.
+     * @param {number} _scale The scaling factor.
      */
     setContentScale(_scale) {
         // NOP
@@ -202,7 +204,6 @@ class PopupWindow extends EventDispatcher {
 
     /**
      * Returns whether or not the popup is currently visible, synchronously.
-     * @returns {boolean} `true` if the popup is visible, `false` otherwise.
      * @throws An exception is thrown for `PopupWindow` since it cannot synchronously detect visibility.
      */
     isVisibleSync() {