Bug 1870226 - Upgrade eslint-plugin-jsdoc to version 43.2.0. r=frontend-codestyle-reviewers,credential-management-reviewers,issammani

This switches from the deprecated/removed jsdoc/newline-after-description rule to using the replacement jsdoc/tag-lines rule.

Differential Revision: https://phabricator.services.mozilla.com/D219512

browser/components/enterprisepolicies/Policies.sys.mjs

@@ -2780,7 +2780,6 @@ export function runOnce(actionName, callback) {
  *        The callback to be run when the pref value changes
  * @returns {Promise}
  *        A promise that will resolve once the callback finishes running.
- *
  */
 async function runOncePerModification(actionName, policyValue, callback) {
   let prefName = `browser.policies.runOncePerModification.${actionName}`;

browser/components/extensions/test/browser/browser_unified_extensions_overflowable_toolbar.js

@@ -104,7 +104,6 @@ function getVisibleMenuItems(popup) {
  *     be run after the window is expanded and the toolbar has underflowed, but
  *     before the extensions are removed. This function is not passed any
  *     arguments. The return value of the function is ignored.
- *
  */
 async function withWindowOverflowed(
   win,

browser/components/places/Interactions.sys.mjs

@@ -100,7 +100,6 @@ function monotonicNow() {
  *   Last updated time as the number of milliseconds since the epoch.
  * @property {string} referrer
  *   The referrer to the url of the page that was interacted with (may be empty)
- *
  */
 
 /**

browser/components/places/PlacesUIUtils.sys.mjs

@@ -648,7 +648,6 @@ export var PlacesUIUtils = {
    * @param {DOMWindow} aWindow
    *        a window on which a potential error alert is shown on.
    * @returns {boolean} true if it's safe to open the node in the browser, false otherwise.
-   *
    */
   checkURLSecurity: function PUIU_checkURLSecurity(aURINode, aWindow) {
     if (lazy.PlacesUtils.nodeIsBookmark(aURINode)) {

browser/components/search/SearchSERPTelemetry.sys.mjs

@@ -2657,7 +2657,6 @@ class DomainToCategoriesMap {
    *
    * @param {object} data
    *  Object containing records that are current, deleted, created, or updated.
-   *
    */
   async #sync(data) {
     lazy.logConsole.debug("Syncing domain-to-categories with Remote Settings.");

browser/components/shopping/ShoppingSidebarChild.sys.mjs

@@ -253,7 +253,6 @@ export class ShoppingSidebarChild extends RemotePageChild {
    *        fetching the URI from the parent, and assume `this.#productURI`
    *        is current. Defaults to false.
    * @param {bool} options.isPolledRequest = false
-   *
    */
   async updateContent({
     haveUpdatedURI = false,

browser/components/uitour/UITour-lib.js

@@ -124,7 +124,6 @@ if (typeof Mozilla == "undefined") {
    * .. code-block:: javascript
    *
    *    [...UITour.targets.keys()].join("\n* - ")
-   *
    */
 
   /**
@@ -399,7 +398,6 @@ if (typeof Mozilla == "undefined") {
    *   DEPRECATED, use 'fxa'
    * - :js:func:`fxa <Mozilla.UITour.Configuration.FxA>`
    * - :js:func:`fxaConnections <Mozilla.UITour.Configuration.FxAConnections>`
-   *
    */
 
   /**

browser/components/urlbar/UrlbarInput.sys.mjs

@@ -896,7 +896,6 @@ export class UrlbarInput {
    *   mode when handing `searchString` from the fake input to the Urlbar.
    * @param {string} newtabSessionId
    *   Optional. The id of the newtab session that handed off this search.
-   *
    */
   handoff(searchString, searchEngine, newtabSessionId) {
     this._isHandoffSession = true;

browser/components/urlbar/UrlbarMuxerUnifiedComplete.sys.mjs

@@ -1382,7 +1382,6 @@ class MuxerUnifiedComplete extends UrlbarMuxer {
    * `result.exposureResultHidden` a boolean which indicates whether the
    * result should be hidden from the view.
    *
-   *
    * @param {UrlbarResult} result
    *   The result.
    * @returns {boolean}

js/xpconnect/loader/XPCOMUtils.sys.mjs

@@ -333,7 +333,6 @@ export var XPCOMUtils = {
    *
    * @param {any} aValue
    *        The value of the non-writable property.
-   *
    */
   defineConstant(aObj, aName, aValue) {
     Object.defineProperty(aObj, aName, {

package-lock.json

@@ -15,7 +15,7 @@
         "eslint-plugin-html": "8.0.0",
         "eslint-plugin-import": "2.29.1",
         "eslint-plugin-jest": "28.5.0",
-        "eslint-plugin-jsdoc": "39.9.1",
+        "eslint-plugin-jsdoc": "43.2.0",
         "eslint-plugin-json": "3.1.0",
         "eslint-plugin-jsx-a11y": "6.8.0",
         "eslint-plugin-mozilla": "file:tools/lint/eslint/eslint-plugin-mozilla",
@@ -250,17 +250,17 @@
       }
     },
     "node_modules/@es-joy/jsdoccomment": {
-      "version": "0.36.1",
+      "version": "0.38.0",
-      "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.36.1.tgz",
+      "resolved": "https://registry.npmjs.org/@es-joy/jsdoccomment/-/jsdoccomment-0.38.0.tgz",
-      "integrity": "sha512-922xqFsTpHs6D0BUiG4toiyPOMc8/jafnWKxz1KWgS4XzKPy2qXf1Pe6UFuNSCQqt6tOuhAWXBNuuyUhJmw9Vg==",
+      "integrity": "sha512-TFac4Bnv0ZYNkEeDnOWHQhaS1elWlvOCQxH06iHeu5iffs+hCaLVIZJwF+FqksQi68R4i66Pu+4DfFGvble+Uw==",
       "dev": true,
       "dependencies": {
         "comment-parser": "1.3.1",
-        "esquery": "^1.4.0",
+        "esquery": "^1.5.0",
-        "jsdoc-type-pratt-parser": "~3.1.0"
+        "jsdoc-type-pratt-parser": "~4.0.0"
       },
       "engines": {
-        "node": "^14 || ^16 || ^17 || ^18 || ^19"
+        "node": ">=16"
       }
     },
     "node_modules/@eslint-community/eslint-utils": {
@@ -658,9 +658,9 @@
       "dev": true
     },
     "node_modules/acorn": {
-      "version": "8.11.3",
+      "version": "8.12.1",
-      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.11.3.tgz",
+      "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.12.1.tgz",
-      "integrity": "sha512-Y9rRfJG5jcKOE0CLisYbojUjIrIEE7AGMzA/Sm4BslANhbS+cDMpgBdcPT91oJ7OuJ9hYJBx59RjbhxVnrF8Xg==",
+      "integrity": "sha512-tcpGyI9zbizT9JbV6oYE477V6mTlXvvi0T0G3SNIYE2apm/G5huBa1+K89VGeovbg+jycCrfhl3ADxErOuO6Jg==",
       "dev": true,
       "bin": {
         "acorn": "bin/acorn"
@@ -740,6 +740,15 @@
         "node": ">= 8"
       }
     },
+    "node_modules/are-docs-informative": {
+      "version": "0.0.2",
+      "resolved": "https://registry.npmjs.org/are-docs-informative/-/are-docs-informative-0.0.2.tgz",
+      "integrity": "sha512-ixiS0nLNNG5jNQzgZJNoUpBKdo9yTYZMGJ+QgT2jmjR7G7+QHRCc4v6LQ3NgE7EBJq+o0ams3waJwkrlBom8Ig==",
+      "dev": true,
+      "engines": {
+        "node": ">=14"
+      }
+    },
     "node_modules/argparse": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
@@ -2018,30 +2027,48 @@
       }
     },
     "node_modules/eslint-plugin-jsdoc": {
-      "version": "39.9.1",
+      "version": "43.2.0",
-      "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-39.9.1.tgz",
+      "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-43.2.0.tgz",
-      "integrity": "sha512-Rq2QY6BZP2meNIs48aZ3GlIlJgBqFCmR55+UBvaDkA3ZNQ0SvQXOs2QKkubakEijV8UbIVbVZKsOVN8G3MuqZw==",
+      "integrity": "sha512-Hst7XUfqh28UmPD52oTXmjaRN3d0KrmOZdgtp4h9/VHUJD3Evoo82ZGXi1TtRDWgWhvqDIRI63O49H0eH7NrZQ==",
       "dev": true,
       "dependencies": {
-        "@es-joy/jsdoccomment": "~0.36.1",
+        "@es-joy/jsdoccomment": "~0.38.0",
+        "are-docs-informative": "^0.0.2",
         "comment-parser": "1.3.1",
         "debug": "^4.3.4",
         "escape-string-regexp": "^4.0.0",
-        "esquery": "^1.4.0",
+        "esquery": "^1.5.0",
-        "semver": "^7.3.8",
+        "semver": "^7.5.0",
         "spdx-expression-parse": "^3.0.1"
       },
       "engines": {
-        "node": "^14 || ^16 || ^17 || ^18 || ^19"
+        "node": ">=16"
       },
       "peerDependencies": {
         "eslint": "^7.0.0 || ^8.0.0"
       }
     },
+    "node_modules/eslint-plugin-jsdoc/node_modules/debug": {
+      "version": "4.3.6",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.6.tgz",
+      "integrity": "sha512-O/09Bd4Z1fBrU4VzkhFqVgpPzaGbw6Sm9FEkBT1A/YBXQFGuuSxa1dN2nxgxS34JmKXqYx8CZAwEVoJFImUXIg==",
+      "dev": true,
+      "dependencies": {
+        "ms": "2.1.2"
+      },
+      "engines": {
+        "node": ">=6.0"
+      },
+      "peerDependenciesMeta": {
+        "supports-color": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/eslint-plugin-jsdoc/node_modules/semver": {
-      "version": "7.6.2",
+      "version": "7.6.3",
-      "resolved": "https://registry.npmjs.org/semver/-/semver-7.6.2.tgz",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.6.3.tgz",
-      "integrity": "sha512-FNAIBWCx9qcRhoHcgcJ0gvU7SN1lYU2ZXuSfl04bSC5OpvDHFyJCjdNHomPXxjQlCBU67YW64PzY7/VIEH7F2w==",
+      "integrity": "sha512-oVekP1cKtI+CTDvHWYFUcMtsK/00wmAEfyqKfNdARm8u1wNVhSgaX7A8d4UuIlUI5e84iEwOhs7ZPYRmzU9U6A==",
       "dev": true,
       "bin": {
         "semver": "bin/semver.js"
@@ -2309,9 +2336,9 @@
       }
     },
     "node_modules/esquery": {
-      "version": "1.5.0",
+      "version": "1.6.0",
-      "resolved": "https://registry.npmjs.org/esquery/-/esquery-1.5.0.tgz",
+      "resolved": "https://registry.npmjs.org/esquery/-/esquery-1.6.0.tgz",
-      "integrity": "sha512-YQLXUplAwJgCydQ78IMJywZCceoqk1oH01OERdSAJc/7U2AylwjhSCLDEtqwg811idIS/9fIU5GjG73IgjKMVg==",
+      "integrity": "sha512-ca9pw9fomFcKPvFLXhBKUK90ZvGibiGOvRJNbjljY7s7uq/5YO4BOzcYtJqExdx99rF6aAcnRxHmcUHcz6sQsg==",
       "dev": true,
       "dependencies": {
         "estraverse": "^5.1.0"
@@ -3463,9 +3490,9 @@
       }
     },
     "node_modules/jsdoc-type-pratt-parser": {
-      "version": "3.1.0",
+      "version": "4.0.0",
-      "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-3.1.0.tgz",
+      "resolved": "https://registry.npmjs.org/jsdoc-type-pratt-parser/-/jsdoc-type-pratt-parser-4.0.0.tgz",
-      "integrity": "sha512-MgtD0ZiCDk9B+eI73BextfRrVQl0oyzRG8B2BjORts6jbunj4ScKPcyXGTbB6eXL4y9TzxCm6hyeLq/2ASzNdw==",
+      "integrity": "sha512-YtOli5Cmzy3q4dP26GraSOeAhqecewG04hoO8DY56CH4KJ9Fvv5qKWUCCo3HZob7esJQHCv6/+bnTy72xZZaVQ==",
       "dev": true,
       "engines": {
         "node": ">=12.0.0"
@@ -5961,12 +5988,13 @@
       }
     },
     "tools/@types": {
+      "name": "@types/gecko",
       "version": "1.0.0",
       "dev": true,
       "license": "MPL-2.0"
     },
     "tools/lint/eslint/eslint-plugin-mozilla": {
-      "version": "3.7.4",
+      "version": "3.7.5",
       "dev": true,
       "license": "MPL-2.0",
       "dependencies": {

package.json

@@ -12,7 +12,7 @@
     "eslint-plugin-html": "8.0.0",
     "eslint-plugin-import": "2.29.1",
     "eslint-plugin-jest": "28.5.0",
-    "eslint-plugin-jsdoc": "39.9.1",
+    "eslint-plugin-jsdoc": "43.2.0",
     "eslint-plugin-json": "3.1.0",
     "eslint-plugin-jsx-a11y": "6.8.0",
     "eslint-plugin-mozilla": "file:tools/lint/eslint/eslint-plugin-mozilla",

remote/cdp/domains/content/Runtime.sys.mjs

@@ -484,7 +484,6 @@ export class Runtime extends ContentProcessDomain {
    *     "default" or "isolated"
    *
    * @returns {number} ID of created context
-   *
    */
   _onContextCreated(name, options = {}) {
     const {

remote/cdp/test/browser/head.js

@@ -468,6 +468,7 @@ class RecordEvents {
    * Then `await record(someTimeout)` to record a timeline that you
    * can make assertions about.
    *
+   * ```js
    * const history = new RecordEvents(expectedNumberOfEvents);
    *
    * history.addRecorder({
@@ -477,11 +478,10 @@ class RecordEvents {
    *     return `Received Runtime.executionContextDestroyed for id ${payload.executionContextId}`;
    *   },
    * });
-   *
+   * ```
    *
    * @param {number} total
    *     Number of expected events. Stop recording when this number is exceeded.
-   *
    */
   constructor(total) {
     this.events = [];

remote/marionette/actors/MarionetteCommandsChild.sys.mjs

@@ -234,7 +234,6 @@ export class MarionetteCommandsChild extends JSWindowActorChild {
    * @param {string} options.selector
    * @param {object} options.opts
    * @param {Element} options.opts.startNode
-   *
    */
   async findElement(options = {}) {
     const { strategy, selector, opts } = options;
@@ -254,7 +253,6 @@ export class MarionetteCommandsChild extends JSWindowActorChild {
    * @param {string} options.selector
    * @param {object} options.opts
    * @param {Element} options.opts.startNode
-   *
    */
   async findElements(options = {}) {
     const { strategy, selector, opts } = options;

remote/shared/TabManager.sys.mjs

@@ -425,7 +425,6 @@ class TabManagerClass {
    * @param {boolean=} options.skipPermitUnload
    *     Flag to indicate if a potential beforeunload prompt should be skipped
    *     when closing the tab. Defaults to false.
-
    */
   async removeTab(tab, options = {}) {
     const { skipPermitUnload = false } = options;

remote/shared/js-window-actors/NavigationListenerChild.sys.mjs

@@ -81,7 +81,6 @@ export class NavigationListenerChild extends JSWindowActorChild {
    *       - browsingContextId: browsing context id
    *       - isTopBrowsingContext: flag that indicates if the browsing context is
    *         top level
-   *
    */
   #getBrowsingContextDetails(browsingContext) {
     return {

remote/shared/listeners/NetworkEventRecord.sys.mjs

@@ -149,7 +149,6 @@ export class NetworkEventRecord {
    *
    * Required API for a NetworkObserver event owner.
    *
-   *
    * @param {object} options
    * @param {nsIChannel} options.channel
    *     The channel.

remote/shared/listeners/test/browser/head.js

@@ -92,7 +92,6 @@ async function loadURL(browser, url) {
  * Create a fetch request to `url` from the content page loaded in the provided
  * `browser`.
  *
- *
  * @param {Browser} browser
  *     The browser element where the fetch should be performed.
  * @param {string} url

toolkit/components/credentialmanagement/CredentialChooserService.sys.mjs

@@ -81,7 +81,6 @@ export class CredentialChooserService {
    * We also support UI-less testing via choices provided by picking any credential with ID 'wpt-pick-me'
    * if the preference 'dom.security.credentialmanagement.chooser.testing.enabled' is true.
    *
-   *
    * @param {BrowsingContext} browsingContext The browsing context of the window calling the Credential Management API.
    * @param {Array<CredentialArgument>} credentials The credentials the user should choose from.
    * @param {nsICredentialChosenCallback} callback A callback to return the user's credential choice to.

toolkit/components/extensions/ExtensionSettingsStore.sys.mjs

@@ -36,7 +36,6 @@
  *     }
  *   }
  * }
- *
  */
 
 import { ExtensionParent } from "resource://gre/modules/ExtensionParent.sys.mjs";

toolkit/components/formautofill/shared/FormStateManager.sys.mjs

@@ -26,7 +26,6 @@ export class FormStateManager {
    * @returns {Array<object> | null}
    *          Return target form's handler from content cache
    *          (or return null if the information is not found in the cache).
-   *
    */
   getFormHandler(element) {
     if (!element) {

toolkit/components/ml/content/EngineProcess.sys.mjs

@@ -476,7 +476,6 @@ export class EngineProcess {
  * @param {object} options - Configuration options for the ML engine.
  * @param {?function(ProgressAndStatusCallbackParams):void} notificationsCallback A function to call to indicate notifications.
  * @returns {Promise<MLEngine>} - A promise that resolves to the ML engine instance.
- *
  */
 export async function createEngine(options, notificationsCallback = null) {
   const pipelineOptions = new PipelineOptions(options);

toolkit/components/search/SearchService.sys.mjs

@@ -411,7 +411,6 @@ export class SearchService {
    *   Returns the pending Promise when #init has started but not yet finished.
    *   | Resolved | when initialization has successfully finished.
    *   | Rejected | when initialization has failed.
-   *
    */
   async init() {
     if (["started", "success", "failed"].includes(this.#initializationStatus)) {
@@ -3284,7 +3283,6 @@ export class SearchService {
    *
    * @param {string} errorType
    *   The error that can occur during search service init.
-   *
    */
   #maybeThrowErrorInTest(errorType) {
     if (
@@ -3617,7 +3615,6 @@ export class SearchService {
    *   The name of the previous default engine that will be replaced.
    * @param {string} newCurrentEngineName
    *   The name of the engine that will be the new default engine.
-   *
    */
   _showRemovalOfSearchEngineNotificationBox(
     prevCurrentEngineName,

toolkit/components/search/SearchSettings.sys.mjs

@@ -420,7 +420,6 @@ export class SearchSettings {
    *
    * @returns {*}
    *   A copy of the settings metadata object.
-   *
    */
   getSettingsMetaData() {
     return { ...this.#settings.metaData };
@@ -438,7 +437,6 @@ export class SearchSettings {
    *   The value of the attribute.
    *   We return undefined if the value of the attribute is not known or does
    *   not match the verification hash.
-   *
    */
   getVerifiedMetaDataAttribute(name, isAppProvided) {
     let attribute = this.getMetaDataAttribute(name);

toolkit/components/shopping/content/ShoppingProduct.mjs

@@ -479,7 +479,6 @@ export class ShoppingProduct extends EventEmitter {
   /**
    * Get a cached, or fetch a copy of, an OHTTP config from a given URL.
    *
-   *
    * @param {string} gatewayConfigURL
    *   The URL for the config that needs to be fetched.
    *   The URL should be complete (i.e. include the full path to the config).

toolkit/components/translations/actors/TranslationsParent.sys.mjs

@@ -1638,7 +1638,6 @@ export class TranslationsParent extends JSWindowActorParent {
    * @param {number} majorVersion
    * @param {string} nextVersion
    * @param {string} [existingVersion]
-   *
    */
   static isBetterRecordVersion(majorVersion, nextVersion, existingVersion) {
     return (

tools/lint/eslint/eslint-plugin-mozilla/lib/configs/valid-jsdoc.js

@@ -16,10 +16,10 @@ module.exports = {
     "jsdoc/check-tag-names": "error",
     "jsdoc/check-types": "error",
     "jsdoc/empty-tags": "error",
-    "jsdoc/newline-after-description": "error",
     "jsdoc/no-multi-asterisks": "error",
     "jsdoc/require-param-type": "error",
     "jsdoc/require-returns-type": "error",
+    "jsdoc/tag-lines": ["error", "any", { startLines: 1 }],
     "jsdoc/valid-types": "error",
   },
   settings: {