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

2 files changed, 23 insertions, 15 deletions

diff --git a/ext/js/data/sandbox/anki-note-data-creator.js b/ext/js/data/sandbox/anki-note-data-creator.js
index 96f97896..e1c32193 100644
--- a/ext/js/data/sandbox/anki-note-data-creator.js
+++ b/ext/js/data/sandbox/anki-note-data-creator.js
@@ -26,7 +26,7 @@
 class AnkiNoteDataCreator {
     /**
      * Creates a new instance.
-     * @param japaneseUtil An instance of `JapaneseUtil`.
+     * @param {JapaneseUtil} japaneseUtil An instance of `JapaneseUtil`.
      */
     constructor(japaneseUtil) {
         this._japaneseUtil = japaneseUtil;
@@ -34,8 +34,16 @@ class AnkiNoteDataCreator {
 
     /**
      * Creates a compatibility representation of the specified data.
-     * @param marker The marker that is being used for template rendering.
-     * @returns An object used for rendering Anki templates.
+     * @param {string} marker The marker that is being used for template rendering.
+     * @param {object} details Information which is used to generate the data.
+     * @param {Translation.DictionaryEntry} details.dictionaryEntry The dictionary entry.
+     * @param {string} details.resultOutputMode The result output mode.
+     * @param {string} details.mode The mode being used to generate the Anki data.
+     * @param {string} details.glossaryLayoutMode The glossary layout mode.
+     * @param {boolean} details.compactTags Whether or not compact tags mode is enabled.
+     * @param {{documentTitle: string, query: string, fullQuery: string}} details.context Contextual information about the source of the dictionary entry.
+     * @param {object} details.media Media data.
+     * @returns {object} An object used for rendering Anki templates.
      */
     create(marker, {
         dictionaryEntry,
@@ -83,8 +91,8 @@ class AnkiNoteDataCreator {
 
     /**
      * Creates a deferred-evaluation value.
-     * @param getter The function to invoke to get the return value.
-     * @returns An object which can be passed into `getCachedValue`.
+     * @param {Function} getter The function to invoke to get the return value.
+     * @returns {{getter: Function, hasValue: false, value: undefined}} An object which can be passed into `getCachedValue`.
      */
     createCachedValue(getter) {
         return {getter, hasValue: false, value: void 0};
@@ -92,8 +100,8 @@ class AnkiNoteDataCreator {
 
     /**
      * Gets the value of a cached object.
-     * @param item An object that was returned from `createCachedValue`.
-     * @returns The result of evaluating the getter, which is cached after the first invocation.
+     * @param {{getter: Function, hasValue: boolean, value: *}} item An object that was returned from `createCachedValue`.
+     * @returns {*} The result of evaluating the getter, which is cached after the first invocation.
      */
     getCachedValue(item) {
         if (item.hasValue) { return item.value; }
diff --git a/ext/js/data/sandbox/string-util.js b/ext/js/data/sandbox/string-util.js
index 5c395be7..de6933cd 100644
--- a/ext/js/data/sandbox/string-util.js
+++ b/ext/js/data/sandbox/string-util.js
@@ -21,8 +21,8 @@
 class StringUtil {
     /**
      * Decodes the contents of an ArrayBuffer using UTF8.
-     * @param arrayBuffer The input ArrayBuffer.
-     * @returns A UTF8-decoded string.
+     * @param {ArrayBuffer} arrayBuffer The input ArrayBuffer.
+     * @returns {string} A UTF8-decoded string.
      */
     static arrayBufferUtf8Decode(arrayBuffer) {
         try {
@@ -34,8 +34,8 @@ class StringUtil {
 
     /**
      * Converts the contents of an ArrayBuffer to a base64 string.
-     * @param arrayBuffer The input ArrayBuffer.
-     * @returns A base64 string representing the binary content.
+     * @param {ArrayBuffer} arrayBuffer The input ArrayBuffer.
+     * @returns {string} A base64 string representing the binary content.
      */
     static arrayBufferToBase64(arrayBuffer) {
         return btoa(this.arrayBufferToBinaryString(arrayBuffer));
@@ -43,8 +43,8 @@ class StringUtil {
 
     /**
      * Converts the contents of an ArrayBuffer to a binary string.
-     * @param arrayBuffer The input ArrayBuffer.
-     * @returns A string representing the binary content.
+     * @param {ArrayBuffer} arrayBuffer The input ArrayBuffer.
+     * @returns {string} A string representing the binary content.
      */
     static arrayBufferToBinaryString(arrayBuffer) {
         const bytes = new Uint8Array(arrayBuffer);
@@ -61,8 +61,8 @@ class StringUtil {
 
     /**
      * Converts a base64 string to an ArrayBuffer.
-     * @param content The binary content string encoded in base64.
-     * @returns A new `ArrayBuffer` object corresponding to the specified content.
+     * @param {string} content The binary content string encoded in base64.
+     * @returns {ArrayBuffer} A new `ArrayBuffer` object corresponding to the specified content.
      */
     static base64ToArrayBuffer(content) {
         const binaryContent = atob(content);