From c661eafa7d57c32e33e51dd6eb787b97832e97f0 Mon Sep 17 00:00:00 2001 From: Cashew <52880648+Scrub1492@users.noreply.github.com> Date: Tue, 19 Dec 2023 12:44:40 +0900 Subject: Add some JSDoc annotations to describe code functionality. (#355) * lesen-tan initial commit * update README.md * tidy up code * opt for Map 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 --- ext/js/data/anki-note-builder.js | 29 +++++++++++++++++++++++++++++ ext/js/data/database.js | 19 ++++++++++++++++--- ext/js/language/deinflector.js | 16 +++++++++++++++- ext/js/language/dictionary-database.js | 28 +++++++++++++++++++++------- 4 files changed, 81 insertions(+), 11 deletions(-) (limited to 'ext') 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} + * @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[]} 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} */ 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} @@ -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} */ 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 . */ +/** + * 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} */ @@ -141,6 +144,7 @@ export class DictionaryDatabase { } /** + * Purges the database. * @returns {Promise} */ 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} */ 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} */ findTermsExactBulk(termList, dictionaries) { @@ -270,6 +277,7 @@ export class DictionaryDatabase { } /** + * Find terms by sequence in bulk. * @param {import('dictionary-database').DictionaryAndQueryRequest[]} items * @returns {Promise} */ @@ -280,6 +288,7 @@ export class DictionaryDatabase { } /** + * Find term meta in bulk. * @param {string[]} termList * @param {import('dictionary-database').DictionarySet} dictionaries * @returns {Promise} @@ -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} */ 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} @@ -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} @@ -343,6 +356,7 @@ export class DictionaryDatabase { } /** + * Get dictionary metadata. * @returns {Promise} */ getDictionaryInfo() { -- cgit v1.2.3