Bug 1389341 - start generating jsdoc for AddonManager API r?kmag draft
authorRobert Helmer <rhelmer@mozilla.com>
Thu, 24 Aug 2017 19:05:59 -0700
changeset 656718 3292c3659887c4b0aad18621b84d296d61965810
parent 656717 4d4d9807674c9f8509e4a7b52f73383e4e009205
child 729221 efe2b9b54db24b2ced65916dd189ac77e9c3b028
push id77299
push userbmo:rhelmer@mozilla.com
push dateThu, 31 Aug 2017 15:52:21 +0000
reviewerskmag
bugs1389341
milestone57.0a1
Bug 1389341 - start generating jsdoc for AddonManager API r?kmag MozReview-Commit-ID: LZf6GfImgMA
toolkit/mozapps/extensions/AddonManager.jsm
toolkit/mozapps/extensions/docs/AddonManager.rst
toolkit/mozapps/extensions/docs/index.rst
tools/docs/conf.py
--- a/toolkit/mozapps/extensions/AddonManager.jsm
+++ b/toolkit/mozapps/extensions/AddonManager.jsm
@@ -618,16 +618,18 @@ var gRepoShutdownState = "";
 var gShutdownInProgress = false;
 var gPluginPageListener = null;
 var gBrowserUpdated = null;
 var gNonMpcDisabled = false;
 
 /**
  * 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(),
@@ -716,16 +718,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);
@@ -920,20 +929,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);
@@ -3280,16 +3287,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.
@@ -3521,20 +3529,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) {
@@ -3689,17 +3699,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);
   },
 
new file mode 100644
--- /dev/null
+++ b/toolkit/mozapps/extensions/docs/AddonManager.rst
@@ -0,0 +1,4 @@
+AddonManager Reference
+======================
+.. js:autoclass:: AddonManager
+  :members:
--- a/toolkit/mozapps/extensions/docs/index.rst
+++ b/toolkit/mozapps/extensions/docs/index.rst
@@ -6,9 +6,10 @@ This is the nascent documentation of the
 
 The public Add-on Manager interfaces are documented on MDN:
 
 https://developer.mozilla.org/en-US/Add-ons/Add-on_Manager
 
 .. toctree::
    :maxdepth: 1
 
+   AddonManager
    SystemAddons
--- a/tools/docs/conf.py
+++ b/tools/docs/conf.py
@@ -36,17 +36,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'
 master_doc = 'index'
 project = u'Mozilla Source Tree Docs'
 year = datetime.now().year