Bug 1869678 - Fixup and improve JSDocs for better type inference r=robwu

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

toolkit/components/extensions/ConduitsParent.sys.mjs

@@ -18,11 +18,25 @@
  * @typedef {number|string} ConduitID
  *
  * @typedef {object} ConduitAddress
- * @property {ConduitID} id Globally unique across all processes.
+ * @property {ConduitID} [id] Globally unique across all processes.
  * @property {string[]} [recv]
  * @property {string[]} [send]
  * @property {string[]} [query]
  * @property {string[]} [cast]
+ *
+ * @property {*} [actor]
+ * @property {boolean} [verified]
+ * @property {string} [url]
+ * @property {number} [frameId]
+ * @property {string} [workerScriptURL]
+ * @property {string} [extensionId]
+ * @property {string} [envType]
+ * @property {string} [instanceId]
+ * @property {number} [portId]
+ * @property {boolean} [native]
+ * @property {boolean} [source]
+ * @property {string} [reportOnClosed]
+ *
  * Lists of recvX, sendX, queryX and castX methods this subject will use.
  *
  * @typedef {"messenger"|"port"|"tab"} BroadcastKind
@@ -295,7 +309,7 @@ export class BroadcastConduit extends BaseConduit {
    * @param {string} method
    * @param {BroadcastKind} kind
    * @param {object} arg
-   * @returns {Promise[]}
+   * @returns {Promise<any[]> | Promise<Response>}
    */
   _cast(method, kind, arg) {
     let filters = {
@@ -335,8 +349,10 @@ export class BroadcastConduit extends BaseConduit {
   /**
    * Custom Promise.race() function that ignores certain resolutions and errors.
    *
-   * @param {Promise<response>[]} promises
-   * @returns {Promise<response?>}
+   * @typedef {{response?: any, received?: boolean}} Response
+   *
+   * @param {Promise<Response>[]} promises
+   * @returns {Promise<Response?>}
    */
   _raceResponses(promises) {
     return new Promise((resolve, reject) => {
@@ -390,7 +406,7 @@ export class ConduitsParent extends JSWindowActorParent {
    * Group webRequest events to send them as a batch, reducing IPC overhead.
    *
    * @param {string} name
-   * @param {MessageData} data
+   * @param {import("ConduitsChild.sys.mjs").MessageData} data
    * @returns {Promise<object>}
    */
   batch(name, data) {
@@ -428,7 +444,7 @@ export class ConduitsParent extends JSWindowActorParent {
    *
    * @param {object} options
    * @param {string} options.name
-   * @param {MessageData} options.data
+   * @param {import("ConduitsChild.sys.mjs").MessageData} options.data
    * @returns {Promise?}
    */
   async receiveMessage({ name, data: { arg, query, sender } }) {

toolkit/components/extensions/Extension.sys.mjs

@@ -900,12 +900,12 @@ export class ExtensionData {
    * @param {object} options
    * @param {nsIURI} options.rootURI
    *  The URI pointing to the extension root.
-   * @param {function(type, id)} options.checkPrivileged
+   * @param {function(type, id): boolean} options.checkPrivileged
    *  An (async) function that takes the addon type and addon ID and returns
    *  whether the given add-on is privileged.
    * @param {boolean} options.temporarilyInstalled
    *  whether the given add-on is installed as temporary.
-   * @returns {ExtensionData}
+   * @returns {Promise<ExtensionData>}
    */
   static async constructAsync({
     rootURI,
@@ -1017,7 +1017,7 @@ export class ExtensionData {
    *   The path to the directory or jar file to look at.
    * @param {boolean} [directoriesOnly]
    *   If true, this will return only the directories present within the directory.
-   * @returns {string[]}
+   * @returns {Promise<string[]>}
    *   An array of names of files/directories (only the name, not the path).
    */
   async _readDirectory(path, directoriesOnly = false) {
@@ -1400,7 +1400,7 @@ export class ExtensionData {
    * be initialized, and manifest parsed prior to calling.
    *
    * @param {string} locale to load, if necessary.
-   * @returns {object} normalized manifest.
+   * @returns {Promise<object>} normalized manifest.
    */
   async getLocalizedManifest(locale) {
     if (!this.type || !this.localeData) {
@@ -2025,6 +2025,7 @@ export class ExtensionData {
   }
 
   getAPIManager() {
+    /** @type {(InstanceType<typeof ExtensionCommon.LazyAPIManager>)[]} */
     let apiManagers = [Management];
 
     for (let id of this.dependencies) {
@@ -2334,10 +2335,10 @@ export class ExtensionData {
    *                 "sideload", "optional", or omitted for a regular
    *                 install prompt.
    * @param {object} options
-   * @param {boolean} options.collapseOrigins
+   * @param {boolean} [options.collapseOrigins]
    *                  Wether to limit the number of displayed host permissions.
    *                  Default is false.
-   * @param {boolean} options.buildOptionalOrigins
+   * @param {boolean} [options.buildOptionalOrigins]
    *                  Wether to build optional origins Maps for permission
    *                  controls.  Defaults to false.
    *
@@ -3361,7 +3362,7 @@ export class Extension extends ExtensionData {
   /**
    * Update site permissions as necessary.
    *
-   * @param {string|undefined} reason
+   * @param {string} [reason]
    *        If provided, this is a BOOTSTRAP_REASON string.  If reason is undefined,
    *        addon permissions are being added or removed that may effect the site permissions.
    */
@@ -3437,6 +3438,7 @@ export class Extension extends ExtensionData {
 
     // readyPromise is resolved with the policy upon success,
     // and with null if startup was interrupted.
+    /** @type {callback} */
     let resolveReadyPromise;
     let readyPromise = new Promise(resolve => {
       resolveReadyPromise = resolve;

toolkit/components/extensions/ExtensionActions.sys.mjs

@@ -121,9 +121,9 @@ class PanelActionBase {
    * @param {XULElement|ChromeWindow|null} target
    *        A XULElement tab, a ChromeWindow, or null for the global data.
    * @param {string} prop
-   *        String property to retrieve. Should should be one of "icon", "title",
-   *        "badgeText", "popup", "badgeBackgroundColor" or "enabled".
-   * @returns {string} value
+   *        Name of property to retrieve. Should should be one of "icon",
+   *        "title", "badgeText", "popup", "badgeBackgroundColor" or "enabled".
+   * @returns {any} value
    *          Value of prop.
    */
   getProperty(target, prop) {

toolkit/components/extensions/ExtensionActivityLog.sys.mjs

@@ -44,7 +44,7 @@ export const ExtensionActivityLog = {
    * @param {string} type The type of the activity.
    * @param {string} name The API name or path.
    * @param {object} data Activity specific data.
-   * @param {string} timeStamp The timestamp for the activity.
+   * @param {Date} [timeStamp] The timestamp for the activity.
    */
   log(id, viewType, type, name, data, timeStamp) {
     if (!this.initialized) {

toolkit/components/extensions/ExtensionChild.sys.mjs

@@ -156,6 +156,7 @@ class SimpleEventAPI extends EventManager {
     super({ context, name, register });
     this.fires = fires;
   }
+  /** @returns {any} */
   emit(...args) {
     return [...this.fires].map(fire => fire.asyncWithoutClone(...args));
   }
@@ -479,6 +480,7 @@ class BrowserExtensionContent extends EventEmitter {
   }
 
   getAPIManager() {
+    /** @type {InstanceType<typeof ExtensionCommon.LazyAPIManager>[]} */
     let apiManagers = [lazy.ExtensionPageChild.apiManager];
 
     if (this.dependencies) {
@@ -870,8 +872,8 @@ class ChildAPIManager {
    *
    * @param {string} path The full name of the method, e.g. "tabs.create".
    * @param {Array} args The parameters for the function.
-   * @param {function(*)} [callback] The callback to be called when the function
-   *     completes.
+   * @param {callback} [callback] The callback to be called when the
+   *      function completes.
    * @param {object} [options] Extra options.
    * @returns {Promise|undefined} Must be void if `callback` is set, and a
    *     promise otherwise. The promise is resolved when the function completes.

toolkit/components/extensions/ExtensionChildDevToolsUtils.sys.mjs

@@ -83,7 +83,8 @@ export var ExtensionChildDevToolsUtils = {
    * destroyed when all of the contexts added to it are closed.
    *
    * @param {string} themeName The name of the current devtools theme.
-   * @param {DevToolsContextChild} context The newly created devtools page context.
+   * @param {import("ExtensionPageChild.sys.mjs").DevToolsContextChild} context
+   *        The newly created devtools page context.
    */
   initThemeChangeObserver(themeName, context) {
     if (!themeChangeObserver) {

toolkit/components/extensions/ExtensionCommon.sys.mjs

@@ -126,7 +126,7 @@ function withHandlingUserInput(window, callable) {
  *        The prototype object on which to define the getter.
  * @param {string | symbol} prop
  *        The property name for which to define the getter.
- * @param {Function} getter
+ * @param {callback} getter
  *        The function to call in order to generate the final property
  *        value.
  */
@@ -251,7 +251,7 @@ class EventEmitter {
    *
    * @param {string} event
    *       The name of the event to listen for.
-   * @param {function(string, ...any)} listener
+   * @param {function(string, ...any): any} listener
    *        The listener to call when events are emitted.
    */
   on(event, listener) {
@@ -269,7 +269,7 @@ class EventEmitter {
    *
    * @param {string} event
    *       The name of the event to stop listening for.
-   * @param {function(string, ...any)} listener
+   * @param {function(string, ...any): any} listener
    *        The listener function to remove.
    */
   off(event, listener) {
@@ -288,7 +288,7 @@ class EventEmitter {
    *
    * @param {string} event
    *       The name of the event to listen for.
-   * @param {function(string, ...any)} listener
+   * @param {function(string, ...any): any} listener
    *        The listener to call when events are emitted.
    */
   once(event, listener) {
@@ -521,7 +521,7 @@ class BaseContext {
    *
    * @param {object} subject
    * @param {ConduitAddress} address
-   * @returns {PointConduit}
+   * @returns {import("ConduitsChild.sys.mjs").PointConduit}
    */
   openConduit(subject, address) {
     let wgc = this.contentWindow.windowGlobalChild;
@@ -583,10 +583,12 @@ class BaseContext {
     throw new Error(`Not implemented for ${this.envType}`);
   }
 
+  /** @type {object} */
   get cloneScope() {
     throw new Error("Not implemented");
   }
 
+  /** @type {nsIPrincipal} */
   get principal() {
     throw new Error("Not implemented");
   }
@@ -743,7 +745,7 @@ class BaseContext {
    * Safely call JSON.stringify() on an object that comes from an
    * extension.
    *
-   * @param {Array<any>} args Arguments for JSON.stringify()
+   * @param {[any, callback?, number?]} args for JSON.stringify()
    * @returns {string} The stringified representation of obj
    */
   jsonStringify(...args) {
@@ -1027,7 +1029,7 @@ class SchemaAPIInterface {
    *
    * @abstract
    * @param {Array} args The parameters for the function.
-   * @param {function(*)} [callback] The callback to be called when the function
+   * @param {callback} [callback] The callback to be called when the function
    *     completes.
    * @param {boolean} [requireUserInput=false] If true, the function should
    *                  fail if the browser is not currently handling user input.
@@ -1446,7 +1448,7 @@ class SchemaAPIManager extends EventEmitter {
    *     "addon" - An addon process.
    *     "content" - A content process.
    *     "devtools" - A devtools process.
-   * @param {SchemaRoot} schema
+   * @param {import("Schemas.sys.mjs").SchemaRoot} [schema]
    */
   constructor(processType, schema) {
     super();
@@ -1695,8 +1697,7 @@ class SchemaAPIManager extends EventEmitter {
    *
    * @param {string} name
    *        The name of the module to load.
-   *
-   * @returns {class}
+   * @returns {typeof ExtensionAPI}
    */
   loadModule(name) {
     let module = this.modules.get(name);
@@ -1721,7 +1722,7 @@ class SchemaAPIManager extends EventEmitter {
    * @param {string} name
    *        The name of the module to load.
    *
-   * @returns {Promise<class>}
+   * @returns {Promise<typeof ExtensionAPI>}
    */
   asyncLoadModule(name) {
     let module = this.modules.get(name);

toolkit/components/extensions/ExtensionContent.sys.mjs

@@ -473,7 +473,7 @@ class Script {
    * Tries to inject this script into the given window and sandbox, if
    * there are pending operations for the window's current load state.
    *
-   * @param {BaseContext} context
+   * @param {ContentScriptContextChild} context
    *        The content script context into which to inject the scripts.
    * @param {boolean} reportExceptions
    *        Defaults to true and reports any exception directly to the console
@@ -606,7 +606,7 @@ class Script {
    *  Get the compiled scripts (if they are already precompiled and cached) or a promise which resolves
    *  to the precompiled scripts (once they have been compiled and cached).
    *
-   * @param {BaseContext} context
+   * @param {ContentScriptContextChild} context
    *        The document to block the parsing on, if the scripts are not yet precompiled and cached.
    *
    * @returns {Array<PreloadedScript> | Promise<Array<PreloadedScript>>}
@@ -1067,6 +1067,11 @@ DocumentManager = {
     },
   },
 
+  /**
+   * @param {object} subject
+   * @param {keyof typeof DocumentManager.observers} topic
+   * @param {any} data
+   */
   observe(subject, topic, data) {
     this.observers[topic].call(this, subject, topic, data);
   },

toolkit/components/extensions/ExtensionDNR.sys.mjs

@@ -579,7 +579,6 @@ class CompiledUrlFilter {
 class RequestDataForUrlFilter {
   /**
    * @param {string} requestURIspec - The URL to match against.
-   * @returns {object} An object to p
    */
   constructor(requestURIspec) {
     // "^" is appended, see CompiledUrlFilter's #initializeUrlFilter.
@@ -634,6 +633,7 @@ class ModifyHeadersBase {
     this.channel = channel;
   }
 
+  /** @param {MatchedRule[]} matchedRules */
   applyModifyHeaders(matchedRules) {
     for (const matchedRule of matchedRules) {
       for (const headerAction of this.headerActionsFor(matchedRule)) {
@@ -714,6 +714,7 @@ class ModifyRequestHeaders extends ModifyHeadersBase {
     }
   }
 
+  /** @param {MatchedRule} matchedRule */
   headerActionsFor(matchedRule) {
     return matchedRule.rule.action.requestHeaders;
   }
@@ -1266,6 +1267,10 @@ function compareRule(ruleA, ruleB, rulesetA, rulesetB) {
 }
 
 class MatchedRule {
+  /**
+   * @param {Rule} rule
+   * @param {Ruleset} ruleset
+   */
   constructor(rule, ruleset) {
     this.rule = rule;
     this.ruleset = ruleset;
@@ -1673,6 +1678,7 @@ class RequestEvaluator {
     return matchedRules;
   }
 
+  /** @param {Ruleset} ruleset */
   #collectMatchInRuleset(ruleset) {
     for (let rule of ruleset.rules) {
       if (!this.#matchesRuleCondition(rule.condition)) {