--- a/toolkit/mozapps/extensions/AddonManager.jsm
+++ b/toolkit/mozapps/extensions/AddonManager.jsm
@@ -617,16 +617,18 @@ var gShutdownBarrier = null;
var gRepoShutdownState = "";
var gShutdownInProgress = false;
var gPluginPageListener = null;
var gBrowserUpdated = null;
/**
* This is the real manager, kept here rather than in AddonManager to keep its
* contents hidden from API users.
+ * @class
+ * @lends AddonManager
*/
var AddonManagerInternal = {
managerListeners: new Set(),
installListeners: new Set(),
addonListeners: new Set(),
typeListeners: new Set(),
pendingProviders: new Set(),
providers: new Set(),
@@ -715,16 +717,23 @@ var AddonManagerInternal = {
appBlocklist.copyTo(profileBlocklist.parent, FILE_BLOCKLIST);
} catch (e) {
logger.warn("Failed to copy the application shipped blocklist to the profile", e);
}
},
/**
* Start up a provider, and register its shutdown hook if it has one
+ *
+ * @param {string} aProvider - An add-on provider.
+ * @param {boolean} aAppChanged - Whether or not the app version has changed since last session.
+ * @param {string} aOldAppVersion - Previous application version, if changed.
+ * @param {string} aOldPlatformVersion - Previous platform version, if changed.
+ *
+ * @private
*/
_startProvider(aProvider, aAppChanged, aOldAppVersion, aOldPlatformVersion) {
if (!gStarted)
throw Components.Exception("AddonManager is not initialized",
Cr.NS_ERROR_NOT_INITIALIZED);
logger.debug(`Starting provider: ${providerName(aProvider)}`);
callProvider(aProvider, "startup", null, aAppChanged, aOldAppVersion, aOldPlatformVersion);
@@ -919,20 +928,18 @@ var AddonManagerInternal = {
logger.debug("Completed startup sequence");
this.callManagerListeners("onStartup");
},
/**
* Registers a new AddonProvider.
*
- * @param aProvider
- * The provider to register
- * @param aTypes
- * An optional array of add-on types
+ * @param {string} aProvider -The provider to register
+ * @param {string[]} [aTypes] - An optional array of add-on types
*/
registerProvider(aProvider, aTypes) {
if (!aProvider || typeof aProvider != "object")
throw Components.Exception("aProvider must be specified",
Cr.NS_ERROR_INVALID_ARG);
if (aTypes && !Array.isArray(aTypes))
throw Components.Exception("aTypes must be an array or null",
@@ -2190,17 +2197,17 @@ var AddonManagerInternal = {
*/
removeInstallListener(aListener) {
if (!aListener || typeof aListener != "object")
throw Components.Exception("aListener must be a InstallListener object",
Cr.NS_ERROR_INVALID_ARG);
this.installListeners.delete(aListener);
},
- /*
+ /**
* Adds new or overrides existing UpgradeListener.
*
* @param aInstanceID
* The instance ID of an addon to register a listener for.
* @param aCallback
* The callback to invoke when updates are available for this addon.
* @throws if there is no addon matching the instanceID
*/
@@ -2243,21 +2250,22 @@ var AddonManagerInternal = {
} else {
throw Error(`No upgrade listener registered for addon ID: ${addon.id}`);
}
});
},
/**
* Installs a temporary add-on from a local file or directory.
+ *
* @param aFile
* An nsIFile for the file or directory of the add-on to be
* temporarily installed.
- * @return a Promise that rejects if the add-on is not a valid restartless
- * add-on or if the same ID is already temporarily installed.
+ * @returns a Promise that rejects if the add-on is not a valid restartless
+ * add-on or if the same ID is already temporarily installed.
*/
installTemporaryAddon(aFile) {
if (!gStarted)
throw Components.Exception("AddonManager is not initialized",
Cr.NS_ERROR_NOT_INITIALIZED);
if (!(aFile instanceof Ci.nsIFile))
throw Components.Exception("aFile must be a nsIFile",
@@ -2374,21 +2382,20 @@ var AddonManagerInternal = {
}
return icons[bestSize] || null;
},
/**
* Asynchronously gets an add-on with a specific ID.
*
- * @param aID
+ * @type {function}
+ * @param {string} aID
* The ID of the add-on to retrieve
- * @return {Promise}
- * @resolves The found Addon or null if no such add-on exists.
- * @rejects Never
+ * @returns {Promise} resolves with the found Addon or null if no such add-on exists. Never rejects.
* @throws if the aID argument is not specified
*/
getAddonByID(aID) {
if (!gStarted)
throw Components.Exception("AddonManager is not initialized",
Cr.NS_ERROR_NOT_INITIALIZED);
if (!aID || typeof aID != "string")
@@ -2562,73 +2569,73 @@ var AddonManagerInternal = {
return addons;
})();
},
/**
* Adds a new AddonManagerListener if the listener is not already registered.
*
- * @param aListener
+ * @param {AddonManagerListener} aListener
* The listener to add
*/
addManagerListener(aListener) {
if (!aListener || typeof aListener != "object")
throw Components.Exception("aListener must be an AddonManagerListener object",
Cr.NS_ERROR_INVALID_ARG);
this.managerListeners.add(aListener);
},
/**
* Removes an AddonManagerListener if the listener is registered.
*
- * @param aListener
+ * @param {AddonManagerListener} aListener
* The listener to remove
*/
removeManagerListener(aListener) {
if (!aListener || typeof aListener != "object")
throw Components.Exception("aListener must be an AddonManagerListener object",
Cr.NS_ERROR_INVALID_ARG);
this.managerListeners.delete(aListener);
},
/**
* Adds a new AddonListener if the listener is not already registered.
*
- * @param aListener
- * The AddonListener to add
+ * @param {AddonManagerListener} aListener
+ * The AddonListener to add.
*/
addAddonListener(aListener) {
if (!aListener || typeof aListener != "object")
throw Components.Exception("aListener must be an AddonListener object",
Cr.NS_ERROR_INVALID_ARG);
this.addonListeners.add(aListener);
},
/**
* Removes an AddonListener if the listener is registered.
*
- * @param aListener
+ * @param {object} aListener
* The AddonListener to remove
*/
removeAddonListener(aListener) {
if (!aListener || typeof aListener != "object")
throw Components.Exception("aListener must be an AddonListener object",
Cr.NS_ERROR_INVALID_ARG);
this.addonListeners.delete(aListener);
},
/**
* Adds a new TypeListener if the listener is not already registered.
*
- * @param aListener
+ * @param {TypeListener} aListener
* The TypeListener to add
*/
addTypeListener(aListener) {
if (!aListener || typeof aListener != "object")
throw Components.Exception("aListener must be a TypeListener object",
Cr.NS_ERROR_INVALID_ARG);
this.typeListeners.add(aListener);
@@ -3276,16 +3283,17 @@ this.AddonManagerPrivate = {
let provider = AddonManagerInternal._getProviderByName("XPIProvider");
return provider ? provider.isDBLoaded : false;
},
};
/**
* This is the public API that UI and developers should be calling. All methods
* just forward to AddonManagerInternal.
+ * @class
*/
this.AddonManager = {
// Constants for the AddonInstall.state property
// These will show up as AddonManager.STATE_* (eg, STATE_AVAILABLE)
_states: new Map([
// The install is available for download.
["STATE_AVAILABLE", 0],
// The install is being downloaded.
@@ -3510,20 +3518,22 @@ this.AddonManager = {
// ask-to-activate. That is, it can be conditionally enabled on a
// case-by-case basis.
STATE_ASK_TO_ACTIVATE: "askToActivate",
get __AddonManagerInternal__() {
return AppConstants.DEBUG ? AddonManagerInternal : undefined;
},
+ /** Boolean indicating whether AddonManager startup has completed. */
get isReady() {
return gStartupComplete && !gShutdownInProgress;
},
+ /** @constructor */
init() {
this._stateToString = new Map();
for (let [name, value] of this._states) {
this[name] = value;
this._stateToString.set(value, name);
}
this._errorToString = new Map();
for (let [name, value] of this._errors) {
@@ -3678,17 +3688,16 @@ this.AddonManager = {
addUpgradeListener(aInstanceID, aCallback) {
AddonManagerInternal.addUpgradeListener(aInstanceID, aCallback);
},
removeUpgradeListener(aInstanceID) {
return AddonManagerInternal.removeUpgradeListener(aInstanceID);
},
-
addAddonListener(aListener) {
AddonManagerInternal.addAddonListener(aListener);
},
removeAddonListener(aListener) {
AddonManagerInternal.removeAddonListener(aListener);
},
--- a/tools/docs/conf.py
+++ b/tools/docs/conf.py
@@ -38,17 +38,17 @@ extensions = [
'sphinx.ext.graphviz',
'sphinx.ext.todo',
'mozbuild.sphinx',
'sphinx_js',
]
# JSDoc must run successfully for dirs specified, so running
# tree-wide (the default) will not work currently.
-js_source_path = []
+js_source_path = ['toolkit/mozapps/extensions']
root_for_relative_js_paths = '.'
jsdoc_config_path = 'tools/docs/jsdoc.json'
templates_path = ['_templates']
source_suffix = '.rst'
source_suffix = ['.rst', '.md']
source_parsers = {
'.md': CommonMarkParser,