aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorCashew <52880648+Scrub1492@users.noreply.github.com>2023-12-19 12:44:40 +0900
committerGitHub <noreply@github.com>2023-12-19 03:44:40 +0000
commitc661eafa7d57c32e33e51dd6eb787b97832e97f0 (patch)
tree1a68a563f9f1960d528595d6b33f74cb506bd77e
parenteb7bf9542c92ea7937d4b4a699ae2d47270da96b (diff)
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
-rw-r--r--dev/build-libs.js4
-rw-r--r--dev/data-error.js3
-rw-r--r--dev/dictionary-validate.js13
-rw-r--r--dev/generate-css-json.js9
-rw-r--r--dev/schema-validate.js1
-rw-r--r--dev/translator-vm.js13
-rw-r--r--dev/util.js1
-rw-r--r--ext/js/data/anki-note-builder.js29
-rw-r--r--ext/js/data/database.js19
-rw-r--r--ext/js/language/deinflector.js16
-rw-r--r--ext/js/language/dictionary-database.js28
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() {