Add some JSDoc annotations to describe code functionality. (#355)

* lesen-tan initial commit

* update README.md

* tidy up code

* opt for Map<K, V> instead of Object

* Document dev/*

* add docs for deinflector.js

* update deinflector example

* Annotate

* Revert "Merge branch 'development' of https://github.com/Scrub1492/lesen-tan into development"

This reverts commit b92348f702bc031b36f24462adfa940d17f9ecdd, reversing
changes made to 3255e6d963281af3533dcf1e893df39032d29fec.

* Lint error fix

* Lint error fix

11 files changed, 112 insertions, 24 deletions

diff --git a/dev/build-libs.js b/dev/build-libs.js
index c3994ab3..a992f20a 100644
--- a/dev/build-libs.js
+++ b/dev/build-libs.js
@@ -45,7 +45,9 @@ async function buildLib(scriptPath) {
     });
 }
 
-/** */
+/**
+ * Bundles libraries.
+ */
 export async function buildLibs() {
     const devLibPath = path.join(dirname, 'lib');
     const files = await fs.promises.readdir(devLibPath, {
diff --git a/dev/data-error.js b/dev/data-error.js
index 5034e3fd..0ab2d354 100644
--- a/dev/data-error.js
+++ b/dev/data-error.js
@@ -15,6 +15,9 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+/**
+ * Schema validation error type.
+ */
 class DataError extends Error {
     /**
      * @param {string} message
diff --git a/dev/dictionary-validate.js b/dev/dictionary-validate.js
index a6948bfe..6778f2ea 100644
--- a/dev/dictionary-validate.js
+++ b/dev/dictionary-validate.js
@@ -71,9 +71,10 @@ async function validateDictionaryBanks(mode, zip, fileNameFormat, schema) {
 }
 
 /**
- * @param {import('dev/schema-validate').ValidateMode} mode
- * @param {import('jszip')} archive
- * @param {import('dev/dictionary-validate').Schemas} schemas
+ * Validates a dictionary.
+ * @param {import('dev/schema-validate').ValidateMode} mode Mode of validation.
+ * @param {import('jszip')} archive Zip archive of the dictionary.
+ * @param {import('dev/dictionary-validate').Schemas} schemas Schema to use for validation.
  */
 export async function validateDictionary(mode, archive, schemas) {
     const fileName = 'index.json';
@@ -102,6 +103,7 @@ export async function validateDictionary(mode, archive, schemas) {
 }
 
 /**
+ * Returns a Schemas object from ext/data/schemas/*.
  * @returns {import('dev/dictionary-validate').Schemas}
  */
 export function getSchemas() {
@@ -118,8 +120,9 @@ export function getSchemas() {
 }
 
 /**
- * @param {import('dev/schema-validate').ValidateMode} mode
- * @param {string[]} dictionaryFileNames
+ * Validates dictionary files and logs the results to the console.
+ * @param {import('dev/schema-validate').ValidateMode} mode Mode of validation.
+ * @param {string[]} dictionaryFileNames Dictionary file names.
  */
 export async function testDictionaryFiles(mode, dictionaryFileNames) {
     const schemas = getSchemas();
diff --git a/dev/generate-css-json.js b/dev/generate-css-json.js
index e5d4d7f0..a0035346 100644
--- a/dev/generate-css-json.js
+++ b/dev/generate-css-json.js
@@ -86,11 +86,11 @@ function removeProperty(styles, property, removedProperties) {
 }
 
 /**
- * @param {import('css-style-applier').RawStyleData} rules
+ * Manually formats JSON for improved compactness.
+ * @param {import('css-style-applier').RawStyleData} rules CSS ruleset.
  * @returns {string}
  */
 export function formatRulesJson(rules) {
-    // Manually format JSON, for improved compactness
     // return JSON.stringify(rules, null, 4);
     const indent1 = '    ';
     const indent2 = indent1.repeat(2);
@@ -123,8 +123,9 @@ export function formatRulesJson(rules) {
 }
 
 /**
- * @param {string} cssFile
- * @param {string} overridesCssFile
+ * Generates a CSS ruleset.
+ * @param {string} cssFile Path to CSS file.
+ * @param {string} overridesCssFile Path to override CSS file.
  * @returns {import('css-style-applier').RawStyleData}
  * @throws {Error}
  */
diff --git a/dev/schema-validate.js b/dev/schema-validate.js
index a1fe8455..81953f49 100644
--- a/dev/schema-validate.js
+++ b/dev/schema-validate.js
@@ -52,6 +52,7 @@ class JsonSchemaAjv {
 }
 
 /**
+ * Creates a JSON Schema.
  * @param {import('dev/schema-validate').ValidateMode} mode
  * @param {import('dev/schema-validate').Schema} schema
  * @returns {JsonSchema|JsonSchemaAjv}
diff --git a/dev/translator-vm.js b/dev/translator-vm.js
index 60777da0..f407e57e 100644
--- a/dev/translator-vm.js
+++ b/dev/translator-vm.js
@@ -32,6 +32,9 @@ vi.mock('../ext/js/language/dictionary-importer-media-loader.js', async () => aw
 
 const dirname = path.dirname(fileURLToPath(import.meta.url));
 
+/**
+ * Translator Virtual Machine.
+ */
 export class TranslatorVM {
     constructor() {
         /** @type {import('dev/vm').PseudoChrome} */
@@ -55,15 +58,19 @@ export class TranslatorVM {
         this._dictionaryName = null;
     }
 
-    /** @type {Translator} */
+    /**
+     * Returns this VM's translator.
+     * @type {Translator}
+     */
     get translator() {
         if (this._translator === null) { throw new Error('Not prepared'); }
         return this._translator;
     }
 
     /**
-     * @param {string} dictionaryDirectory
-     * @param {string} dictionaryName
+     * Initialize this translator VM from a dictionary.
+     * @param {string} dictionaryDirectory Directory of the dictionary files.
+     * @param {string} dictionaryName Name of the dictionary.
      */
     async prepare(dictionaryDirectory, dictionaryName) {
         // Dictionary
diff --git a/dev/util.js b/dev/util.js
index c27ccb2d..f45966c4 100644
--- a/dev/util.js
+++ b/dev/util.js
@@ -97,6 +97,7 @@ export function getAllFiles(baseDirectory, predicate = null) {
 }
 
 /**
+ * Creates a zip archive from the given dictionary directory.
  * @param {string} dictionaryDirectory
  * @param {string} [dictionaryName]
  * @returns {import('jszip')}
diff --git a/ext/js/data/anki-note-builder.js b/ext/js/data/anki-note-builder.js
index 864bd2d4..80cc210a 100644
--- a/ext/js/data/anki-note-builder.js
+++ b/ext/js/data/anki-note-builder.js
@@ -22,9 +22,16 @@ import {TemplateRendererProxy} from '../templates/template-renderer-proxy.js';
 import {yomitan} from '../yomitan.js';
 import {AnkiUtil} from './anki-util.js';
 
+/**
+ * Anki Note Builder Class.
+ */
 export class AnkiNoteBuilder {
     /**
+     * Initiate an instance of AnkiNoteBuilder.
      * @param {{japaneseUtil: import('../language/sandbox/japanese-util.js').JapaneseUtil}} details
+     * @example
+     * const japaneseUtil = new JapaneseUtil(null);
+     * const ankiNoteBuilder = new AnkiNoteBuilder({japaneseUtil});
      */
     constructor({japaneseUtil}) {
         /** @type {import('../language/sandbox/japanese-util.js').JapaneseUtil} */
@@ -40,8 +47,30 @@ export class AnkiNoteBuilder {
     }
 
     /**
+     * Creates an Anki note.
      * @param {import('anki-note-builder').CreateNoteDetails} details
      * @returns {Promise<import('anki-note-builder').CreateNoteResult>}
+     * @example
+     * const ankiNoteBuilder = new AnkiNoteBuilder({japaneseUtil});
+     * const details = {
+     *     dictionaryEntry,
+     *     mode: 'test',
+     *     context,
+     *     template,
+     *     deckName: 'deckName',
+     *     modelName: 'modelName',
+     *     fields,
+     *     tags: ['yomitan'],
+     *     checkForDuplicates: true,
+     *     duplicateScope: 'collection',
+     *     duplicateScopeCheckAllModels: false,
+     *     resultOutputMode: mode,
+     *     glossaryLayoutMode: 'default',
+     *     compactTags: false,
+     *     requirements: [],
+     *     mediaOptions: null
+     * };
+     * const {note: {fields: noteFields}, errors} = await ankiNoteBuilder.createNote(details);
      */
     async createNote({
         dictionaryEntry,
diff --git a/ext/js/data/database.js b/ext/js/data/database.js
index 8b9e7354..cb09a680 100644
--- a/ext/js/data/database.js
+++ b/ext/js/data/database.js
@@ -17,6 +17,7 @@
  */
 
 /**
+ * Database class to store objects.
  * @template {string} TObjectStoreName
  */
 export class Database {
@@ -28,6 +29,7 @@ export class Database {
     }
 
     /**
+     * Opens the DB.
      * @param {string} databaseName
      * @param {number} version
      * @param {import('database').StructureDefinition<TObjectStoreName>[]} structure
@@ -51,6 +53,7 @@ export class Database {
     }
 
     /**
+     * Closes the DB.
      * @throws {Error}
      */
     close() {
@@ -63,6 +66,7 @@ export class Database {
     }
 
     /**
+     * Returns true if DB opening is in process.
      * @returns {boolean}
      */
     isOpening() {
@@ -70,6 +74,7 @@ export class Database {
     }
 
     /**
+     * Returns true if the DB is open.
      * @returns {boolean}
      */
     isOpen() {
@@ -77,6 +82,7 @@ export class Database {
     }
 
     /**
+     * Returns a new transaction with the given mode ("readonly" or "readwrite") and scope which can be a single object store name or an array of names.
      * @param {string[]} storeNames
      * @param {IDBTransactionMode} mode
      * @returns {IDBTransaction}
@@ -90,10 +96,12 @@ export class Database {
     }
 
     /**
+     * Add items in bulk to the object store.
+     * count items will be added beginning from start index of items list.
      * @param {TObjectStoreName} objectStoreName
-     * @param {unknown[]} items
-     * @param {number} start
-     * @param {number} count
+     * @param {unknown[]} items List of items to add.
+     * @param {number} start Start index. Added items begin at items[start].
+     * @param {number} count Count of items to add.
      * @returns {Promise<void>}
      */
     bulkAdd(objectStoreName, items, start, count) {
@@ -244,6 +252,7 @@ export class Database {
     }
 
     /**
+     * Deletes records in store with the given key or in the given key range in query.
      * @param {TObjectStoreName} objectStoreName
      * @param {IDBValidKey|IDBKeyRange} key
      * @returns {Promise<void>}
@@ -258,6 +267,7 @@ export class Database {
     }
 
     /**
+     * Delete items in bulk from the object store.
      * @param {TObjectStoreName} objectStoreName
      * @param {?string} indexName
      * @param {IDBKeyRange} query
@@ -291,6 +301,9 @@ export class Database {
     }
 
     /**
+     * Attempts to delete the named database.
+     * If the database already exists and there are open connections that don't close in response to a versionchange event, the request will be blocked until all they close.
+     * If the request is successful request's result will be null.
      * @param {string} databaseName
      * @returns {Promise<void>}
      */
diff --git a/ext/js/language/deinflector.js b/ext/js/language/deinflector.js
index 537a4556..90ca79ea 100644
--- a/ext/js/language/deinflector.js
+++ b/ext/js/language/deinflector.js
@@ -16,9 +16,17 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+/**
+ * This class deinflects Japanese terms to its dictionary form.
+ */
 export class Deinflector {
     /**
      * @param {import('deinflector').ReasonsRaw} reasons
+     * @example
+     * const deinflectionReasons = JSON.parse(
+     *   readFileSync(path.join('ext/data/deinflect.json')).toString(),
+     * ) as object;
+     * const deinflector = new Deinflector(deinflectionReasons);
      */
     constructor(reasons) {
         /** @type {import('deinflector').Reason[]} */
@@ -26,8 +34,13 @@ export class Deinflector {
     }
 
     /**
-     * @param {string} source
+     * Deinflects a Japanese term to all of its possible dictionary forms.
+     * @param {string} source The source term to deinflect.
      * @returns {import('translation-internal').Deinflection[]}
+     * @example
+     * const deinflector = new Deinflector(deinflectionReasons);
+     * // [{ term: '食べた', rules: 0, reasons: [] }, { term: '食べる', rules: 1, reasons: ['past'] }, { term: '食ぶ', rules: 2, reasons: ['potential', 'past'] }]
+     * console.log(deinflector.deinflect('食べさせられる'));
      */
     deinflect(source) {
         const results = [this._createDeinflection(source, 0, [])];
@@ -88,6 +101,7 @@ export class Deinflector {
     }
 
     /**
+     * Given a list of rules, return the corresponding deinflection rule flags.
      * @param {string[]} rules
      * @returns {import('translation-internal').DeinflectionRuleFlags}
      */
diff --git a/ext/js/language/dictionary-database.js b/ext/js/language/dictionary-database.js
index c47e1e90..ce5041c8 100644
--- a/ext/js/language/dictionary-database.js
+++ b/ext/js/language/dictionary-database.js
@@ -19,6 +19,9 @@
 import {log, stringReverse} from '../core.js';
 import {Database} from '../data/database.js';
 
+/**
+ * This class represents the dictionary database.
+ */
 export class DictionaryDatabase {
     constructor() {
         /** @type {Database<import('dictionary-database').ObjectStoreName>} */
@@ -141,6 +144,7 @@ export class DictionaryDatabase {
     }
 
     /**
+     * Purges the database.
      * @returns {Promise<boolean>}
      */
     async purge() {
@@ -162,6 +166,7 @@ export class DictionaryDatabase {
     }
 
     /**
+     * Deletes a dictionary.
      * @param {string} dictionaryName
      * @param {number} progressRate
      * @param {import('dictionary-database').DeleteDictionaryProgressCallback} onProgress
@@ -225,9 +230,10 @@ export class DictionaryDatabase {
     }
 
     /**
-     * @param {string[]} termList
-     * @param {import('dictionary-database').DictionarySet} dictionaries
-     * @param {import('dictionary-database').MatchType} matchType
+     * Find terms in bulk.
+     * @param {string[]} termList The list of terms to find.
+     * @param {import('dictionary-database').DictionarySet} dictionaries Dictionaries to find the terms from.
+     * @param {import('dictionary-database').MatchType} matchType Matching type.
      * @returns {Promise<import('dictionary-database').TermEntry[]>}
      */
     findTermsBulk(termList, dictionaries, matchType) {
@@ -259,8 +265,9 @@ export class DictionaryDatabase {
     }
 
     /**
-     * @param {import('dictionary-database').TermExactRequest[]} termList
-     * @param {import('dictionary-database').DictionarySet} dictionaries
+     * Find exact terms in bulk.
+     * @param {import('dictionary-database').TermExactRequest[]} termList The list of terms to find.
+     * @param {import('dictionary-database').DictionarySet} dictionaries Dictionaries to find the term from.
      * @returns {Promise<import('dictionary-database').TermEntry[]>}
      */
     findTermsExactBulk(termList, dictionaries) {
@@ -270,6 +277,7 @@ export class DictionaryDatabase {
     }
 
     /**
+     * Find terms by sequence in bulk.
      * @param {import('dictionary-database').DictionaryAndQueryRequest[]} items
      * @returns {Promise<import('dictionary-database').TermEntry[]>}
      */
@@ -280,6 +288,7 @@ export class DictionaryDatabase {
     }
 
     /**
+     * Find term meta in bulk.
      * @param {string[]} termList
      * @param {import('dictionary-database').DictionarySet} dictionaries
      * @returns {Promise<import('dictionary-database').TermMeta[]>}
@@ -291,8 +300,9 @@ export class DictionaryDatabase {
     }
 
     /**
-     * @param {string[]} kanjiList
-     * @param {import('dictionary-database').DictionarySet} dictionaries
+     * Find kanji in bulk.
+     * @param {string[]} kanjiList The list of kanji to find.
+     * @param {import('dictionary-database').DictionarySet} dictionaries Dictionaries to find from.
      * @returns {Promise<import('dictionary-database').KanjiEntry[]>}
      */
     findKanjiBulk(kanjiList, dictionaries) {
@@ -302,6 +312,7 @@ export class DictionaryDatabase {
     }
 
     /**
+     * Find kanji meta in bulk.
      * @param {string[]} kanjiList
      * @param {import('dictionary-database').DictionarySet} dictionaries
      * @returns {Promise<import('dictionary-database').KanjiMeta[]>}
@@ -313,6 +324,7 @@ export class DictionaryDatabase {
     }
 
     /**
+     * Find tag meta in bulk.
      * @param {import('dictionary-database').DictionaryAndQueryRequest[]} items
      * @returns {Promise<(import('dictionary-database').Tag|undefined)[]>}
      */
@@ -323,6 +335,7 @@ export class DictionaryDatabase {
     }
 
     /**
+     * Find tag for title.
      * @param {string} name
      * @param {string} dictionary
      * @returns {Promise<?import('dictionary-database').Tag>}
@@ -343,6 +356,7 @@ export class DictionaryDatabase {
     }
 
     /**
+     * Get dictionary metadata.
      * @returns {Promise<import('dictionary-importer').Summary[]>}
      */
     getDictionaryInfo() {