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 --- dev/build-libs.js | 4 +++- dev/data-error.js | 3 +++ dev/dictionary-validate.js | 13 ++++++++----- dev/generate-css-json.js | 9 +++++---- dev/schema-validate.js | 1 + dev/translator-vm.js | 13 ++++++++++--- dev/util.js | 1 + 7 files changed, 31 insertions(+), 13 deletions(-) (limited to 'dev') 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 . */ +/** + * 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')} -- cgit v1.2.3