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, 38 insertions, 20 deletions

diff --git a/ext/js/comm/clipboard-reader.js b/ext/js/comm/clipboard-reader.js
index 7a4744ca..aaf4dcd8 100644
--- a/ext/js/comm/clipboard-reader.js
+++ b/ext/js/comm/clipboard-reader.js
@@ -25,9 +25,10 @@
 class ClipboardReader {
     /**
      * Creates a new instances of a clipboard reader.
-     * @param document The Document object to be used, or null for no support.
-     * @param pasteTargetSelector The selector for the paste target element.
-     * @param imagePasteTargetSelector The selector for the image paste target element.
+     * @param {object} details Details about how to set up the instance.
+     * @param {?Document} details.document The Document object to be used, or null for no support.
+     * @param {?string} details.pasteTargetSelector The selector for the paste target element.
+     * @param {?string} details.imagePasteTargetSelector The selector for the image paste target element.
      */
     constructor({document=null, pasteTargetSelector=null, imagePasteTargetSelector=null}) {
         this._document = document;
@@ -40,6 +41,7 @@ class ClipboardReader {
 
     /**
      * Gets the browser being used.
+     * @type {?string}
      */
     get browser() {
         return this._browser;
@@ -54,8 +56,8 @@ class ClipboardReader {
 
     /**
      * Gets the text in the clipboard.
-     * @returns A string containing the clipboard text.
-     * @throws Error if not supported.
+     * @returns {string} A string containing the clipboard text.
+     * @throws {Error} Error if not supported.
      */
     async getText() {
         /*
@@ -103,8 +105,8 @@ class ClipboardReader {
 
     /**
      * Gets the first image in the clipboard.
-     * @returns A string containing a data URL of the image file, or null if no image was found.
-     * @throws Error if not supported.
+     * @returns {string} A string containing a data URL of the image file, or null if no image was found.
+     * @throws {Error} Error if not supported.
      */
     async getImage() {
         // See browser-specific notes in getText
diff --git a/ext/js/comm/frame-ancestry-handler.js b/ext/js/comm/frame-ancestry-handler.js
index cff31ce0..56daafe9 100644
--- a/ext/js/comm/frame-ancestry-handler.js
+++ b/ext/js/comm/frame-ancestry-handler.js
@@ -24,7 +24,7 @@
 class FrameAncestryHandler {
     /**
      * Creates a new instance.
-     * @param frameId The frame ID of the current frame the instance is instantiated in.
+     * @param {number} frameId The frame ID of the current frame the instance is instantiated in.
      */
     constructor(frameId) {
         this._frameId = frameId;
@@ -37,6 +37,7 @@ class FrameAncestryHandler {
 
     /**
      * Gets the frame ID that the instance is instantiated in.
+     * @type {number}
      */
     get frameId() {
         return this._frameId;
@@ -53,7 +54,7 @@ class FrameAncestryHandler {
 
     /**
      * Returns whether or not this frame is the root frame in the tab.
-     * @returns `true` if it is the root, otherwise `false`.
+     * @returns {boolean} `true` if it is the root, otherwise `false`.
      */
     isRootFrame() {
         return (window === window.parent);
@@ -63,8 +64,7 @@ class FrameAncestryHandler {
      * Gets the frame ancestry information for the current frame. If the frame is the
      * root frame, an empty array is returned. Otherwise, an array of frame IDs is returned,
      * starting from the nearest ancestor.
-     * @param timeout The maximum time to wait to receive a response to frame information requests.
-     * @returns An array of frame IDs corresponding to the ancestors of the current frame.
+     * @returns {number[]} An array of frame IDs corresponding to the ancestors of the current frame.
      */
     async getFrameAncestryInfo() {
         if (this._getFrameAncestryInfoPromise === null) {
@@ -77,8 +77,8 @@ class FrameAncestryHandler {
      * Gets the frame element of a child frame given a frame ID.
      * For this function to work, the `getFrameAncestryInfo` function needs to have
      * been invoked previously.
-     * @param frameId The frame ID of the child frame to get.
-     * @returns The element corresponding to the frame with ID `frameId`, otherwise `null`.
+     * @param {number} frameId The frame ID of the child frame to get.
+     * @returns {HTMLElement} The element corresponding to the frame with ID `frameId`, otherwise `null`.
      */
     getChildFrameElement(frameId) {
         const frameInfo = this._childFrameMap.get(frameId);
diff --git a/ext/js/comm/mecab.js b/ext/js/comm/mecab.js
index 9be8b75f..24364588 100644
--- a/ext/js/comm/mecab.js
+++ b/ext/js/comm/mecab.js
@@ -21,6 +21,21 @@
  */
 class Mecab {
     /**
+     * The resulting data from an invocation of `parseText`.
+     * @typedef {object} ParseResult
+     * @property {string} name The dictionary name for the parsed result.
+     * @property {ParseTerm[]} lines The resulting parsed terms.
+     */
+
+    /**
+     * A fragment of the parsed text.
+     * @typedef {object} ParseFragment
+     * @property {string} term The term.
+     * @property {string} reading The reading of the term.
+     * @property {string} source The source text.
+     */
+
+    /**
      * Creates a new instance of the class.
      */
     constructor() {
@@ -37,6 +52,7 @@ class Mecab {
 
     /**
      * Returns whether or not the component is enabled.
+     * @returns {boolean} Whether or not the object is enabled.
      */
     isEnabled() {
         return this._enabled;
@@ -44,7 +60,7 @@ class Mecab {
 
     /**
      * Changes whether or not the component connection is enabled.
-     * @param enabled A boolean indicating whether or not the component should be enabled.
+     * @param {boolean} enabled A boolean indicating whether or not the component should be enabled.
      */
     setEnabled(enabled) {
         this._enabled = !!enabled;
@@ -64,7 +80,7 @@ class Mecab {
 
     /**
      * Returns whether or not the connection to the native application is active.
-     * @returns `true` if the connection is active, `false` otherwise.
+     * @returns {boolean} `true` if the connection is active, `false` otherwise.
      */
     isConnected() {
         return (this._port !== null);
@@ -72,7 +88,7 @@ class Mecab {
 
     /**
      * Returns whether or not any invocation is currently active.
-     * @returns `true` if an invocation is active, `false` otherwise.
+     * @returns {boolean} `true` if an invocation is active, `false` otherwise.
      */
     isActive() {
         return (this._invocations.size > 0);
@@ -80,7 +96,7 @@ class Mecab {
 
     /**
      * Gets the local API version being used.
-     * @returns An integer representing the API version that Yomichan uses.
+     * @returns {number} An integer representing the API version that Yomichan uses.
      */
     getLocalVersion() {
         return this._version;
@@ -88,7 +104,7 @@ class Mecab {
 
     /**
      * Gets the version of the MeCab component.
-     * @returns The version of the MeCab component, or `null` if the component was not found.
+     * @returns {?number} The version of the MeCab component, or `null` if the component was not found.
      */
     async getVersion() {
         try {
@@ -115,8 +131,8 @@ class Mecab {
      *     ...
      * ]
      * ```
-     * @param text The string to parse.
-     * @returns A collection of parsing results of the text.
+     * @param {string} text The string to parse.
+     * @returns {ParseResult[]} A collection of parsing results of the text.
      */
     async parseText(text) {
         await this._setupPort();