From 5dd28ecc35d5e49a100047d40ee4ca7a10009619 Mon Sep 17 00:00:00 2001
From: Greg Tatum <tatum.creative@gmail.com>
Date: Wed, 13 Mar 2024 19:23:41 +0000
Subject: [PATCH] Bug 1814289 - Enable the jsdoc lint rule for translations and
 run auto-fix; r=translations-reviewers,nordzilla

There will be lint errors reported, as the following patch will manually
fix the remaining errors.

Differential Revision: https://phabricator.services.mozilla.com/D204516
---
 .eslintrc.js                                  |  1 -
 .../TranslationsTelemetry.sys.mjs             |  3 ++
 .../actors/AboutTranslationsChild.sys.mjs     |  1 +
 .../actors/TranslationsChild.sys.mjs          |  1 +
 .../actors/TranslationsEngineChild.sys.mjs    |  3 +-
 .../actors/TranslationsParent.sys.mjs         | 36 ++++++++++-------
 .../content/translations-document.sys.mjs     | 39 +++++++++++++------
 .../content/translations-engine.sys.mjs       |  4 ++
 .../translations/content/translations.mjs     |  5 ++-
 .../translations/tests/browser/shared-head.js | 32 ++++++++-------
 10 files changed, 81 insertions(+), 44 deletions(-)

diff --git a/.eslintrc.js b/.eslintrc.js
index 3b2dae0a93a0..54e0db4bdf90 100644
--- a/.eslintrc.js
+++ b/.eslintrc.js
@@ -597,7 +597,6 @@ module.exports = {
         "toolkit/components/thumbnails/**",
         "toolkit/components/timermanager/UpdateTimerManager.*",
         "toolkit/components/translation/LanguageDetector.*",
-        "toolkit/components/translations/**",
         "toolkit/components/url-classifier/**",
         "toolkit/components/utils/**",
         "toolkit/components/viewsource/**",
diff --git a/toolkit/components/translations/TranslationsTelemetry.sys.mjs b/toolkit/components/translations/TranslationsTelemetry.sys.mjs
index f01ee1d1443f..8550a1c1aff2 100644
--- a/toolkit/components/translations/TranslationsTelemetry.sys.mjs
+++ b/toolkit/components/translations/TranslationsTelemetry.sys.mjs
@@ -41,6 +41,7 @@ export class TranslationsTelemetry {
 
   /**
    * Telemetry functions for the Translations panel.
+   *
    * @returns {Panel}
    */
   static panel() {
@@ -49,6 +50,7 @@ export class TranslationsTelemetry {
 
   /**
    * Forces the creation of a new Translations telemetry flowId and returns it.
+   *
    * @returns {string}
    */
   static createFlowId() {
@@ -60,6 +62,7 @@ export class TranslationsTelemetry {
   /**
    * Returns a Translations telemetry flowId by retrieving the cached value
    * if available, or creating a new one otherwise.
+   *
    * @returns {string}
    */
   static getOrCreateFlowId() {
diff --git a/toolkit/components/translations/actors/AboutTranslationsChild.sys.mjs b/toolkit/components/translations/actors/AboutTranslationsChild.sys.mjs
index 1eb4a6ed0288..9d0b27a6a1a0 100644
--- a/toolkit/components/translations/actors/AboutTranslationsChild.sys.mjs
+++ b/toolkit/components/translations/actors/AboutTranslationsChild.sys.mjs
@@ -183,6 +183,7 @@ export class AboutTranslationsChild extends JSWindowActorChild {
 
   /**
    * Does this device support the translation engine?
+   *
    * @returns {Promise<boolean>}
    */
   AT_isTranslationEngineSupported() {
diff --git a/toolkit/components/translations/actors/TranslationsChild.sys.mjs b/toolkit/components/translations/actors/TranslationsChild.sys.mjs
index a3f8d15c8542..d318b7284f73 100644
--- a/toolkit/components/translations/actors/TranslationsChild.sys.mjs
+++ b/toolkit/components/translations/actors/TranslationsChild.sys.mjs
@@ -24,6 +24,7 @@ export class TranslationsChild extends JSWindowActorChild {
   /**
    * This cache is shared across TranslationsChild instances. This means
    * that it will be shared across multiple page loads in the same origin.
+   *
    * @type {LRUCache | null}
    */
   static #translationsCache = null;
diff --git a/toolkit/components/translations/actors/TranslationsEngineChild.sys.mjs b/toolkit/components/translations/actors/TranslationsEngineChild.sys.mjs
index e1d0d4f99d9e..a390025dbd08 100644
--- a/toolkit/components/translations/actors/TranslationsEngineChild.sys.mjs
+++ b/toolkit/components/translations/actors/TranslationsEngineChild.sys.mjs
@@ -19,6 +19,7 @@ export class TranslationsEngineChild extends JSWindowActorChild {
   /**
    * The resolve function for the Promise returned by the
    * "TranslationsEngine:ForceShutdown" message.
+   *
    * @type {null | () => {}}
    */
   #resolveForceShutdown = null;
@@ -130,7 +131,7 @@ export class TranslationsEngineChild extends JSWindowActorChild {
   }
 
   /**
-   * @param {Object} options
+   * @param {object} options
    * @param {number?} options.startTime
    * @param {string} options.message
    */
diff --git a/toolkit/components/translations/actors/TranslationsParent.sys.mjs b/toolkit/components/translations/actors/TranslationsParent.sys.mjs
index 9c83e15ae785..3f5914fe43c6 100644
--- a/toolkit/components/translations/actors/TranslationsParent.sys.mjs
+++ b/toolkit/components/translations/actors/TranslationsParent.sys.mjs
@@ -142,11 +142,11 @@ const VERIFY_SIGNATURES_FROM_FS = false;
  */
 
 /**
- * @typedef {Object} TranslationPair
- * @prop {string} fromLanguage
- * @prop {string} toLanguage
- * @prop {string} [fromDisplayLanguage]
- * @prop {string} [toDisplayLanguage]
+ * @typedef {object} TranslationPair
+ * @property {string} fromLanguage
+ * @property {string} toLanguage
+ * @property {string} [fromDisplayLanguage]
+ * @property {string} [toDisplayLanguage]
  */
 
 /**
@@ -332,6 +332,7 @@ export class TranslationsParent extends JSWindowActorParent {
 
   /**
    * Telemetry functions for Translations
+   *
    * @returns {TranslationsTelemetry}
    */
   static telemetry() {
@@ -351,6 +352,7 @@ export class TranslationsParent extends JSWindowActorParent {
   /**
    * Offer translations (for instance by automatically opening the popup panel) whenever
    * languages are detected, but only do it once per host per session.
+   *
    * @param {LangTags} detectedLanguages
    */
   maybeOfferTranslations(detectedLanguages) {
@@ -553,6 +555,7 @@ export class TranslationsParent extends JSWindowActorParent {
 
   /**
    * Provide a way for tests to override the system locales.
+   *
    * @type {null | string[]}
    */
   static mockedSystemLocales = null;
@@ -848,6 +851,7 @@ export class TranslationsParent extends JSWindowActorParent {
 
   /**
    * The cached language pairs.
+   *
    * @type {Promise<Array<LanguagePair>> | null}
    */
   static #languagePairs = null;
@@ -937,7 +941,7 @@ export class TranslationsParent extends JSWindowActorParent {
   /**
    * Create a unique list of languages, sorted by the display name.
    *
-   * @param {Object} supportedLanguages
+   * @param {object} supportedLanguages
    * @returns {Array<{ langTag: string, displayName: string}}
    */
   static getLanguageList(supportedLanguages) {
@@ -966,8 +970,8 @@ export class TranslationsParent extends JSWindowActorParent {
   }
 
   /**
-   * @param {Object} event
-   * @param {Object} event.data
+   * @param {object} event
+   * @param {object} event.data
    * @param {TranslationModelRecord[]} event.data.created
    * @param {TranslationModelRecord[]} event.data.updated
    * @param {TranslationModelRecord[]} event.data.deleted
@@ -1043,8 +1047,8 @@ export class TranslationsParent extends JSWindowActorParent {
    * then only the 1.1-version record will be returned in the resulting collection.
    *
    * @param {RemoteSettingsClient} remoteSettingsClient
-   * @param {Object} [options]
-   *   @param {Object} [options.filters={}]
+   * @param {object} [options]
+   *   @param {object} [options.filters={}]
    *     The filters to apply when retrieving the records from RemoteSettings.
    *     Filters should correspond to properties on the RemoteSettings records themselves.
    *     For example, A filter to retrieve only records with a `fromLang` value of "en" and a `toLang` value of "es":
@@ -1503,6 +1507,7 @@ export class TranslationsParent extends JSWindowActorParent {
 
   /**
    * Delete all language model files.
+   *
    * @returns {Promise<string[]>} A list of record IDs.
    */
   static async deleteAllLanguageFiles() {
@@ -1860,6 +1865,7 @@ export class TranslationsParent extends JSWindowActorParent {
   /**
    * Report an error. Having this as a method allows tests to check that an error
    * was properly reported.
+   *
    * @param {Error} error - Providing an Error object makes sure the stack is properly
    *                        reported.
    * @param {any[]} args - Any args to pass on to console.error.
@@ -2740,11 +2746,11 @@ class TranslationsLanguageState {
 }
 
 /**
- * @typedef {Object} QueueItem
- * @prop {Function} download
- * @prop {Function} [onSuccess]
- * @prop {Function} [onFailure]
- * @prop {number} [retriesLeft]
+ * @typedef {object} QueueItem
+ * @property {Function} download
+ * @property {Function} [onSuccess]
+ * @property {Function} [onFailure]
+ * @property {number} [retriesLeft]
  */
 
 /**
diff --git a/toolkit/components/translations/content/translations-document.sys.mjs b/toolkit/components/translations/content/translations-document.sys.mjs
index 7f436575d8f4..ccf4a7d62b28 100644
--- a/toolkit/components/translations/content/translations-document.sys.mjs
+++ b/toolkit/components/translations/content/translations-document.sys.mjs
@@ -254,7 +254,7 @@ export class TranslationsDocument {
   /**
    * The BCP 47 language tag that is used on the page.
    *
-   * @type {string} */
+    @type {string} */
   documentLanguage;
 
   /**
@@ -475,8 +475,9 @@ export class TranslationsDocument {
 
   /**
    * Queue a node for translation of attributes.
+   *
    * @param {Node} node
-   * @param {Array<String>}
+   * @param {Array<string>}
    */
   queueAttributeNodeForTranslation(node, attributeList) {
     /** @type {NodeVisibility} */
@@ -522,6 +523,7 @@ export class TranslationsDocument {
   /**
    * Helper function for adding a new root to the mutation
    * observer.
+   *
    * @param {Node} root
    */
   observeNewRoot(root) {
@@ -689,6 +691,7 @@ export class TranslationsDocument {
    * Get all the nodes which have selected attributes
    * from the node/document and queue them.
    * Call the translate function on these nodes
+   *
    * @param {Node} node
    * @returns {Array<Promise<void>> | null}
    */
@@ -773,7 +776,7 @@ export class TranslationsDocument {
    * Runs `determineTranslationStatus`, but only on unprocessed nodes.
    *
    * @param {Node} node
-   * @return {number} - One of the NodeStatus values.
+   * @returns {number} - One of the NodeStatus values.
    */
   determineTranslationStatusForUnprocessedNodes = node => {
     if (this.#processedNodes.has(node)) {
@@ -840,6 +843,7 @@ export class TranslationsDocument {
 
   /**
    * Queue a node for translation.
+   *
    * @param {Node} node
    */
   queueNodeForTranslation(node) {
@@ -856,6 +860,7 @@ export class TranslationsDocument {
 
   /**
    * Submit the translations giving priority to nodes in the viewport.
+   *
    * @returns {Array<Promise<void>> | null}
    */
   dispatchQueuedTranslations() {
@@ -905,6 +910,7 @@ export class TranslationsDocument {
 
   /**
    * Submit the Attribute translations giving priority to nodes in the viewport.
+   *
    * @returns {Array<Promise<void>> | null}
    */
   dispatchQueuedAttributeTranslations() {
@@ -1124,9 +1130,10 @@ export class TranslationsDocument {
   /**
    * A single function to update pendingTranslationsCount while
    * calling the translate function
+   *
    * @param {Node} node
    * @param {string} text
-   * @prop {boolean} isHTML
+   * @property {boolean} isHTML
    * @returns {Promise<string | null>}
    */
   async maybeTranslate(node, text, isHTML) {
@@ -1223,6 +1230,7 @@ export class TranslationsDocument {
   /**
    * Stop the mutations so that the updates of the translations
    * in the nodes won't trigger observations.
+   *
    * @param {Function} run The function to update translations
    */
   pauseMutationObserverAndRun(run) {
@@ -1286,6 +1294,7 @@ export class TranslationsDocument {
 /**
  * Get the list of attributes that need to be translated
  * in a given node.
+ *
  * @returns Array<string>
  */
 function getTranslatableAttributes(node) {
@@ -1342,7 +1351,7 @@ function langTagsMatch(knownLanguage, otherLanguage) {
  * style of node.
  *
  * @param {Node} node
- * @returns {HTMLElement} */
+  @returns {HTMLElement} */
 function getElementForStyle(node) {
   if (node.nodeType != Node.TEXT_NODE) {
     return node;
@@ -1424,6 +1433,7 @@ function updateElement(translationsDocument, element) {
 
   /**
    * The Set of translation IDs for nodes that have been cloned.
+   *
    * @type {Set<number>}
    */
   const clonedNodes = new Set();
@@ -1649,6 +1659,7 @@ function removeTextNodes(node) {
  *   - `<p>test</p>`: yes
  *   - `<p> </p>`: no
  *   - `<p><b>test</b></p>`: no
+ *
  * @param {Node} node
  * @returns {boolean}
  */
@@ -1795,12 +1806,12 @@ function* getAncestorsIterator(node) {
 /**
  * This contains all of the information needed to perform a translation request.
  *
- * @typedef {Object} TranslationRequest
- * @prop {Node} node
- * @prop {string} sourceText
- * @prop {boolean} isHTML
- * @prop {Function} resolve
- * @prop {Function} reject
+ * @typedef {object} TranslationRequest
+ * @property {Node} node
+ * @property {string} sourceText
+ * @property {boolean} isHTML
+ * @property {Function} resolve
+ * @property {Function} reject
  */
 
 /**
@@ -1827,6 +1838,7 @@ class QueuedTranslator {
 
   /**
    * Tie together a message id to a resolved response.
+   *
    * @type {Map<number, TranslationRequest}
    */
   #requests = new Map();
@@ -1834,6 +1846,7 @@ class QueuedTranslator {
   /**
    * If the translations are paused, they are queued here. This Map is ordered by
    * from oldest to newest requests with stale requests being removed.
+   *
    * @type {Map<Node, TranslationRequest>}
    */
   #queue = new Map();
@@ -1902,6 +1915,7 @@ class QueuedTranslator {
   /**
    * Request a new port. The port will come in via `acquirePort`, and then resolved
    * through the `this.#portRequest.resolve`.
+   *
    * @returns {Promise<void>}
    */
   #requestNewPort() {
@@ -1997,7 +2011,7 @@ class QueuedTranslator {
    * @param {Node} node
    * @param {string} sourceText
    * @param {boolean} isHTML
-   * @return {{ translateText: TranslationFunction, translateHTML: TranslationFunction}}
+   * @returns {{ translateText: TranslationFunction, translateHTML: TranslationFunction}}
    */
   #postTranslationRequest(node, sourceText, isHTML) {
     return new Promise((resolve, reject) => {
@@ -2049,6 +2063,7 @@ class QueuedTranslator {
   /**
    * Acquires a port, checks on the engine status, and then starts or resumes
    * translations.
+   *
    * @param {MessagePort} port
    */
   acquirePort(port) {
diff --git a/toolkit/components/translations/content/translations-engine.sys.mjs b/toolkit/components/translations/content/translations-engine.sys.mjs
index e9aeb8076b4e..1d8796f0d5a0 100644
--- a/toolkit/components/translations/content/translations-engine.sys.mjs
+++ b/toolkit/components/translations/content/translations-engine.sys.mjs
@@ -150,6 +150,7 @@ export class TranslationsEngine {
 
   /**
    * Removes the engine, and if it's the last, call the process to destroy itself.
+   *
    * @param {string} languagePairKey
    * @param {boolean} force - On forced shutdowns, it's not necessary to notify the
    *                          parent process.
@@ -207,6 +208,7 @@ export class TranslationsEngine {
 
   /**
    * Terminates the engine and its worker after a timeout.
+   *
    * @param {boolean} force
    */
   terminate = (force = false) => {
@@ -419,6 +421,7 @@ function getLanguagePairKey(fromLanguage, toLanguage) {
 
 /**
  * Maps the innerWindowId to the port.
+ *
  * @type {Map<number, { fromLanguage: string, toLanguage: string, port: MessagePort }}
  */
 const ports = new Map();
@@ -427,6 +430,7 @@ const ports = new Map();
  * Listen to the port to the content process for incoming messages, and pass
  * them to the TranslationsEngine manager. The other end of the port is held
  * in the content process by the TranslationsDocument.
+ *
  * @param {string} fromLanguage
  * @param {string} toLanguage
  * @param {number} innerWindowId
diff --git a/toolkit/components/translations/content/translations.mjs b/toolkit/components/translations/content/translations.mjs
index 0ec8b2d47550..65746745c53e 100644
--- a/toolkit/components/translations/content/translations.mjs
+++ b/toolkit/components/translations/content/translations.mjs
@@ -57,6 +57,7 @@ class TranslationsState {
 
   /**
    * Only send one translation in at a time to the worker.
+   *
    * @type {Promise<string[]>}
    */
   translationRequest = Promise.resolve([]);
@@ -75,6 +76,7 @@ class TranslationsState {
   constructor(isSupported) {
     /**
      * Is the engine supported by the device?
+     *
      * @type {boolean}
      */
     this.isTranslationEngineSupported = isSupported;
@@ -607,7 +609,7 @@ window.addEventListener("AboutTranslationsChromeToContent", ({ detail }) => {
  * Debounce a function so that it is only called after some wait time with no activity.
  * This is good for grouping text entry via keyboard.
  *
- * @param {Object} settings
+ * @param {object} settings
  * @param {Function} settings.onDebounce
  * @param {Function} settings.doEveryTime
  * @returns {Function}
@@ -671,6 +673,7 @@ class Translator {
 
   /**
    * Tie together a message id to a resolved response.
+   *
    * @type {Map<number, TranslationRequest}
    */
   #requests = new Map();
diff --git a/toolkit/components/translations/tests/browser/shared-head.js b/toolkit/components/translations/tests/browser/shared-head.js
index 9be4db9c3c91..7e4e1bd2f95e 100644
--- a/toolkit/components/translations/tests/browser/shared-head.js
+++ b/toolkit/components/translations/tests/browser/shared-head.js
@@ -149,6 +149,7 @@ async function openAboutTranslations({
 /**
  * Naively prettify's html based on the opening and closing tags. This is not robust
  * for general usage, but should be adequate for these tests.
+ *
  * @param {string} html
  * @returns {string}
  */
@@ -358,6 +359,7 @@ async function closeAllOpenPanelsAndMenus() {
 
 /**
  * Closes the popup element with the given Id if it is open.
+ *
  * @param {string} popupElementId
  */
 async function closePopupIfOpen(popupElementId) {
@@ -655,7 +657,8 @@ async function captureTranslationsError(callback) {
 
 /**
  * Load a test page and run
- * @param {Object} options - The options for `loadTestPage` plus a `runInPage` function.
+ *
+ * @param {object} options - The options for `loadTestPage` plus a `runInPage` function.
  */
 async function autoTranslatePage(options) {
   const { prefs, languagePairs, ...otherOptions } = options;
@@ -827,7 +830,7 @@ let _remoteSettingsMockId = 0;
  * Creates a local RemoteSettingsClient for use within tests.
  *
  * @param {boolean} autoDownloadFromRemoteSettings
- * @param {Object[]} langPairs
+ * @param {object[]} langPairs
  * @returns {RemoteSettingsClient}
  */
 async function createTranslationModelsRemoteClient(
@@ -981,7 +984,7 @@ function hitEnterKey(button, message) {
  *
  * @see assertVisibility
  *
- * @param {Object} options
+ * @param {object} options
  * @param {string} options.message
  * @param {Record<string, Element[]>} options.visible
  * @param {Record<string, Element[]>} options.hidden
@@ -1012,7 +1015,7 @@ async function ensureVisibility({ message = null, visible = {}, hidden = {} }) {
 /**
  * Asserts that the provided elements are either visible or hidden.
  *
- * @param {Object} options
+ * @param {object} options
  * @param {string} options.message
  * @param {Record<string, Element[]>} options.visible
  * @param {Record<string, Element[]>} options.hidden
@@ -1137,8 +1140,8 @@ class TestTranslationsTelemetry {
    * Asserts qualities about a counter telemetry metric.
    *
    * @param {string} name - The name of the metric.
-   * @param {Object} counter - The Glean counter object.
-   * @param {Object} expectedCount - The expected value of the counter.
+   * @param {object} counter - The Glean counter object.
+   * @param {object} expectedCount - The expected value of the counter.
    */
   static async assertCounter(name, counter, expectedCount) {
     // Ensures that glean metrics are collected from all child processes
@@ -1156,15 +1159,15 @@ class TestTranslationsTelemetry {
    * Asserts qualities about an event telemetry metric.
    *
    * @param {string} name - The name of the metric.
-   * @param {Object} event - The Glean event object.
-   * @param {Object} expectations - The test expectations.
+   * @param {object} event - The Glean event object.
+   * @param {object} expectations - The test expectations.
    * @param {number} expectations.expectedEventCount - The expected count of events.
    * @param {boolean} expectations.expectNewFlowId
    * - Expects the flowId to be different than the previous flowId if true,
    *   and expects it to be the same if false.
-   * @param {Array<function>} [expectations.allValuePredicates=[]]
+   * @param {Array<Function>} [expectations.allValuePredicates=[]]
    * - An array of function predicates to assert for all event values.
-   * @param {Array<function>} [expectations.finalValuePredicates=[]]
+   * @param {Array<Function>} [expectations.finalValuePredicates=[]]
    * - An array of function predicates to assert for only the final event value.
    */
   static async assertEvent(
@@ -1264,8 +1267,8 @@ class TestTranslationsTelemetry {
    * Asserts qualities about a rate telemetry metric.
    *
    * @param {string} name - The name of the metric.
-   * @param {Object} rate - The Glean rate object.
-   * @param {Object} expectations - The test expectations.
+   * @param {object} rate - The Glean rate object.
+   * @param {object} expectations - The test expectations.
    * @param {number} expectations.expectedNumerator - The expected value of the numerator.
    * @param {number} expectations.expectedDenominator - The expected value of the denominator.
    */
@@ -1346,9 +1349,10 @@ function getNeverTranslateSitesFromPerms() {
 
 /**
  * Opens a dialog window for about:preferences
+ *
  * @param {string} dialogUrl - The URL of the dialog window
  * @param {Function} callback - The function to open the dialog via UI
- * @returns {Object} The dialog window object
+ * @returns {object} The dialog window object
  */
 async function waitForOpenDialogWindow(dialogUrl, callback) {
   const dialogLoaded = promiseLoadSubDialog(dialogUrl);
@@ -1360,7 +1364,7 @@ async function waitForOpenDialogWindow(dialogUrl, callback) {
 /**
  * Closes an open dialog window and waits for it to close.
  *
- * @param {Object} dialogWindow
+ * @param {object} dialogWindow
  */
 async function waitForCloseDialogWindow(dialogWindow) {
   const closePromise = BrowserTestUtils.waitForEvent(