update JSDoc comments (#387)

* 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 b92348f, reversing changes made to 3255e6d. * Lint error fix * Lint error fix * update JSDoc comments --------- Co-authored-by: Darius Jahandarie <[email protected]>
yomidevs · Dec 19, 2023 · 5f96276 · 5f96276
1 parent 7b93055
commit 5f96276
Show file tree

Hide file tree

Showing 5 changed files with 18 additions and 67 deletions.
diff --git a/dev/dictionary-validate.js b/dev/dictionary-validate.js
@@ -71,10 +71,10 @@ async function validateDictionaryBanks(mode, zip, fileNameFormat, schema) {
 }
 
 /**
- * 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.
+ * Validates a dictionary from its zip archive.
+ * @param {import('dev/schema-validate').ValidateMode} mode
+ * @param {import('jszip')} archive
+ * @param {import('dev/dictionary-validate').Schemas} schemas
  */
 export async function validateDictionary(mode, archive, schemas) {
     const fileName = 'index.json';
@@ -121,8 +121,8 @@ export function getSchemas() {
 
 /**
  * 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.
+ * @param {import('dev/schema-validate').ValidateMode} mode
+ * @param {string[]} dictionaryFileNames
  */
 export async function testDictionaryFiles(mode, dictionaryFileNames) {
     const schemas = getSchemas();

diff --git a/ext/js/data/anki-note-builder.js b/ext/js/data/anki-note-builder.js
@@ -22,16 +22,10 @@ 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} */
@@ -47,30 +41,8 @@ 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
@@ -17,7 +17,6 @@
  */
 
 /**
- * Database class to store objects.
  * @template {string} TObjectStoreName
  */
 export class Database {
@@ -29,7 +28,6 @@ export class Database {
     }
 
     /**
-     * Opens the DB.
      * @param {string} databaseName
      * @param {number} version
      * @param {import('database').StructureDefinition<TObjectStoreName>[]} structure
@@ -53,7 +51,6 @@ export class Database {
     }
 
     /**
-     * Closes the DB.
      * @throws {Error}
      */
     close() {
@@ -66,15 +63,15 @@ export class Database {
     }
 
     /**
-     * Returns true if DB opening is in process.
+     * Returns true if the database opening is in process.
      * @returns {boolean}
      */
     isOpening() {
         return this._isOpening;
     }
 
     /**
-     * Returns true if the DB is open.
+     * Returns true if the database is fully opened.
      * @returns {boolean}
      */
     isOpen() {
@@ -97,10 +94,10 @@ export class Database {
 
     /**
      * Add items in bulk to the object store.
-     * count items will be added beginning from start index of items list.
+     * _count_ items will be added, starting from _start_ index of _items_ list.
      * @param {TObjectStoreName} objectStoreName
      * @param {unknown[]} items List of items to add.
-     * @param {number} start Start index. Added items begin at items[start].
+     * @param {number} start Start index. Added items begin at _items_[_start_].
      * @param {number} count Count of items to add.
      * @returns {Promise<void>}
      */

diff --git a/ext/js/language/deinflector.js b/ext/js/language/deinflector.js
@@ -16,16 +16,13 @@
  * 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) {
@@ -101,7 +98,6 @@ 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
@@ -19,9 +19,6 @@
 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>} */
@@ -144,7 +141,6 @@ export class DictionaryDatabase {
     }
 
     /**
-     * Purges the database.
      * @returns {Promise<boolean>}
      */
     async purge() {
@@ -166,7 +162,6 @@ export class DictionaryDatabase {
     }
 
     /**
-     * Deletes a dictionary.
      * @param {string} dictionaryName
      * @param {number} progressRate
      * @param {import('dictionary-database').DeleteDictionaryProgressCallback} onProgress
@@ -230,10 +225,9 @@ export class DictionaryDatabase {
     }
 
     /**
-     * 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.
+     * @param {string[]} termList
+     * @param {import('dictionary-database').DictionarySet} dictionaries
+     * @param {import('dictionary-database').MatchType} matchType
      * @returns {Promise<import('dictionary-database').TermEntry[]>}
      */
     findTermsBulk(termList, dictionaries, matchType) {
@@ -265,9 +259,8 @@ export class DictionaryDatabase {
     }
 
     /**
-     * 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.
+     * @param {import('dictionary-database').TermExactRequest[]} termList
+     * @param {import('dictionary-database').DictionarySet} dictionaries
      * @returns {Promise<import('dictionary-database').TermEntry[]>}
      */
     findTermsExactBulk(termList, dictionaries) {
@@ -277,7 +270,6 @@ export class DictionaryDatabase {
     }
 
     /**
-     * Find terms by sequence in bulk.
      * @param {import('dictionary-database').DictionaryAndQueryRequest[]} items
      * @returns {Promise<import('dictionary-database').TermEntry[]>}
      */
@@ -288,7 +280,6 @@ export class DictionaryDatabase {
     }
 
     /**
-     * Find term meta in bulk.
      * @param {string[]} termList
      * @param {import('dictionary-database').DictionarySet} dictionaries
      * @returns {Promise<import('dictionary-database').TermMeta[]>}
@@ -300,9 +291,8 @@ export class DictionaryDatabase {
     }
 
     /**
-     * Find kanji in bulk.
-     * @param {string[]} kanjiList The list of kanji to find.
-     * @param {import('dictionary-database').DictionarySet} dictionaries Dictionaries to find from.
+     * @param {string[]} kanjiList
+     * @param {import('dictionary-database').DictionarySet} dictionaries
      * @returns {Promise<import('dictionary-database').KanjiEntry[]>}
      */
     findKanjiBulk(kanjiList, dictionaries) {
@@ -312,7 +302,6 @@ export class DictionaryDatabase {
     }
 
     /**
-     * Find kanji meta in bulk.
      * @param {string[]} kanjiList
      * @param {import('dictionary-database').DictionarySet} dictionaries
      * @returns {Promise<import('dictionary-database').KanjiMeta[]>}
@@ -324,7 +313,6 @@ export class DictionaryDatabase {
     }
 
     /**
-     * Find tag meta in bulk.
      * @param {import('dictionary-database').DictionaryAndQueryRequest[]} items
      * @returns {Promise<(import('dictionary-database').Tag|undefined)[]>}
      */
@@ -335,7 +323,6 @@ export class DictionaryDatabase {
     }
 
     /**
-     * Find tag for title.
      * @param {string} name
      * @param {string} dictionary
      * @returns {Promise<?import('dictionary-database').Tag>}
@@ -356,7 +343,6 @@ export class DictionaryDatabase {
     }
 
     /**
-     * Get dictionary metadata.
      * @returns {Promise<import('dictionary-importer').Summary[]>}
      */
     getDictionaryInfo() {