Bug 1861865 - Fix ESLint valid-jsdoc issues in various browser code and enable on directories where it is already passing. r=Gijs

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

Author: Standard8

.eslintrc.js

@@ -240,18 +240,13 @@ module.exports = {
         "browser/components/pocket/content/pkt*",
         "browser/components/preferences/**",
         "browser/components/privatebrowsing/**",
-        "browser/components/prompts/PromptCollection.sys.mjs",
-        "browser/components/protocolhandler/WebProtocolHandlerRegistrar.sys.mjs",
         "browser/components/safebrowsing/content/test/**",
         "browser/components/screenshots/**",
         "browser/components/sessionstore/**",
         "browser/components/storybook/.storybook/**",
         "browser/components/tests/browser/**",
-        "browser/components/touchbar/tests/browser/browser_touchbar_searchrestrictions.js",
         "browser/extensions/screenshots/**",
         "browser/modules/**",
-        "browser/themes/BuiltInThemes.sys.mjs",
-        "browser/tools/mozscreenshots/**",
         "devtools/**",
         "docshell/base/URIFixup.sys.mjs",
         "dom/**",

browser/components/prompts/PromptCollection.sys.mjs

@@ -4,6 +4,7 @@
 
 /**
  * Implements nsIPromptCollection
+ *
  * @class PromptCollection
  */
 export class PromptCollection {

browser/components/protocolhandler/WebProtocolHandlerRegistrar.sys.mjs

@@ -52,11 +52,11 @@ WebProtocolHandlerRegistrar.prototype = {
   /**
    * Determines if a web handler is already registered.
    *
-   * @param aProtocol
+   * @param {string} aProtocol
    *        The scheme of the web handler we are checking for.
-   * @param aURITemplate
+   * @param {string} aURITemplate
    *        The URI template that the handler uses to handle the protocol.
-   * @return true if it is already registered, false otherwise.
+   * @returns {boolean} true if it is already registered, false otherwise.
    */
   _protocolHandlerRegistered(aProtocol, aURITemplate) {
     let eps = Cc[

browser/components/touchbar/tests/browser/browser_touchbar_searchrestrictions.js

@@ -27,9 +27,10 @@ XPCOMUtils.defineLazyServiceGetter(
  */
 
 /**
- * @param {string} input
+ * @param {object} options
+ * @param {string} options.input
  *   The value to be inserted in the Urlbar.
- * @param {UrlbarTokenizer.RESTRICT} token
+ * @param {UrlbarTokenizer.RESTRICT} options.token
  *   A restriction token corresponding to a Touch Bar button.
  */
 async function searchAndCheckState({ input, token }) {

browser/themes/BuiltInThemes.sys.mjs

@@ -116,14 +116,15 @@ class _BuiltInThemes {
   }
 
   /**
+   * This looks up the id in a Map rather than accessing a property on
+   * the addon itself. That makes calls to this function O(m) where m is the
+   * total number of built-in themes offered now or in the past. Since we
+   * are using a Map, calls are O(1) in the average case.
+   *
    * @param {string} id
    *   A theme's ID.
    * @returns {boolean}
    *   Returns true if the theme is expired. False otherwise.
-   * @note This looks up the id in a Map rather than accessing a property on
-   *   the addon itself. That makes calls to this function O(m) where m is the
-   *   total number of built-in themes offered now or in the past. Since we
-   *   are using a Map, calls are O(1) in the average case.
    */
   themeIsExpired(id) {
     let themeInfo = this.builtInThemeMap.get(id);
@@ -133,7 +134,7 @@ class _BuiltInThemes {
   /**
    * @param {string} id
    *   The theme's id.
-   * @return {boolean}
+   * @returns {boolean}
    *   True if the theme with id `id` is both expired and retained. That is,
    *   the user has the ability to use it after its expiry date.
    */
@@ -144,7 +145,7 @@ class _BuiltInThemes {
   /**
    * @param {string} id
    *   The theme's id.
-   * @return {boolean}
+   * @returns {boolean}
    *   True if the theme with id `id` is from the currently active theme.
    */
   isActiveTheme(id) {
@@ -216,6 +217,7 @@ class _BuiltInThemes {
   /**
    * Set a pref to ensure that the user can continue to use a specified theme
    * past its expiry date.
+   *
    * @param {string} id
    *   The ID of the theme to retain.
    */
@@ -233,6 +235,7 @@ class _BuiltInThemes {
    * Removes from the retained expired theme list colorways themes that have been
    * migrated from the one installed in the built-in XPIProvider location
    * to an AMO hosted xpi installed in the user profile XPIProvider location.
+   *
    * @param {string} id
    *   The ID of the theme to remove from the retained themes list.
    */
@@ -255,9 +258,10 @@ class _BuiltInThemes {
    * same base color but with different intensities (soft, balanced, and bold),
    * or if the current collection doesn't have intensities, each colorway is
    * their own group. Group name localization is optional.
-   * @param {string} id
+   *
+   * @param {string} colorwayId
    *   The ID of the colorway add-on.
-   * @return {string}
+   * @returns {string}
    *   Localized colorway group name. null if there's no such name, in which
    *   case the caller should fall back on getting a name from the add-on API.
    */
@@ -266,9 +270,9 @@ class _BuiltInThemes {
   }
 
   /**
-   * @param {string} id
+   * @param {string} colorwayId
    *   The ID of the colorway add-on.
-   * @return {string}
+   * @returns {string}
    *   L10nId for intensity value of the colorway with the provided id, null if
    *   there's none.
    */
@@ -280,9 +284,9 @@ class _BuiltInThemes {
   }
 
   /**
-   * @param {string} id
+   * @param {string} colorwayId
    *   The ID of the colorway add-on.
-   * @return {string}
+   * @returns {string}
    *   Localized description of the colorway with the provided id, null if
    *   there's none.
    */

browser/tools/mozscreenshots/head.js

@@ -41,8 +41,10 @@ async function setup() {
 
 /**
  * Used by pre-defined sets of configurations to decide whether to run for a build.
- * @note This is not used by browser_screenshots.js which handles when MOZSCREENSHOTS_SETS is set.
- * @return {bool} whether to capture screenshots.
+ *
+ * This is not used by browser_screenshots.js which handles when MOZSCREENSHOTS_SETS is set.
+ *
+ * @returns {bool} whether to capture screenshots.
  */
 function shouldCapture() {
   if (Services.env.get("MOZSCREENSHOTS_SETS")) {

browser/tools/mozscreenshots/mozscreenshots/extension/TestRunner.sys.mjs

@@ -155,8 +155,9 @@ export var TestRunner = {
   /**
    * Helper function for loadSets. This filters out the restricted configs from setName.
    * This was made a helper function to facilitate xpcshell unit testing.
-   * @param {String} setName - set name to be filtered e.g. "Toolbars[onlyNavBar,allToolbars]"
-   * @return {Object} Returns an object with two values: the filtered set name and a set of
+   *
+   * @param {string} setName - set name to be filtered e.g. "Toolbars[onlyNavBar,allToolbars]"
+   * @returns {object} Returns an object with two values: the filtered set name and a set of
    *                  restricted configs.
    */
   filterRestrictions(setName) {
@@ -175,8 +176,9 @@ export var TestRunner = {
 
   /**
    * Load sets of configurations from JSMs.
-   * @param {String[]} setNames - array of set names (e.g. ["Tabs", "WindowSize"].
-   * @return {Object[]} Array of sets containing `name` and `configurations` properties.
+   *
+   * @param {string[]} setNames - array of set names (e.g. ["Tabs", "WindowSize"].
+   * @returns {object[]} Array of sets containing `name` and `configurations` properties.
    */
   loadSets(setNames) {
     let sets = [];
@@ -243,9 +245,10 @@ export var TestRunner = {
   /**
    * Calculate the bounding box based on CSS selector from config for cropping
    *
-   * @param {String[]} selectors - array of CSS selectors for relevant DOM element
-   * @return {Geometry.sys.mjs Rect} Rect holding relevant x, y, width, height with padding
-   **/
+   * @param {string[]} selectors - array of CSS selectors for relevant DOM element
+   * @returns {Rect}
+   *   A Geometry.sys.mjs Rect holding relevant x, y, width, height with padding
+   */
   _findBoundingBox(selectors, windowType) {
     if (!selectors.length) {
       throw new Error("No selectors specified.");
@@ -564,8 +567,9 @@ export var TestRunner = {
 
   /**
    * Finds the index of the first comma that is not enclosed within square brackets.
-   * @param {String} envVar - the string that needs to be searched
-   * @return {Integer} index of valid comma or -1 if not found.
+   *
+   * @param {string} envVar - the string that needs to be searched
+   * @returns {number} index of valid comma or -1 if not found.
    */
   findComma(envVar) {
     let nestingDepth = 0;
@@ -584,8 +588,9 @@ export var TestRunner = {
 
   /**
    * Splits the environment variable around commas not enclosed in brackets.
-   * @param {String} envVar - The environment variable
-   * @return {String[]} Array of strings containing the configurations
+   *
+   * @param {string} envVar - The environment variable
+   * @returns {string[]} Array of strings containing the configurations
    * e.g. ["Toolbars[onlyNavBar,allToolbars]","DevTools[jsdebugger,webconsole]","Tabs"]
    */
   splitEnv(envVar) {
@@ -604,7 +609,7 @@ export var TestRunner = {
 
 /**
  * Helper to lazily compute the Cartesian product of all of the sets of configurations.
- **/
+ */
 function LazyProduct(sets) {
   /**
    * An entry for each set with the value being: