Bug 1278733: Turn on JSDoc validation, and fix basic errors in existing comments. r=aswan

MozReview-Commit-ID: EZpOyvoi2h0

--HG--
extra : rebase_source : b03b211a1fe3aad3c760bd0f9235bbaaca171a9a

browser/components/extensions/ext-commands.js

@@ -65,7 +65,9 @@ CommandList.prototype = {
 
   /**
    * Creates a Map from commands for each command in the manifest.commands object.
+   *
    * @param {Object} manifest The manifest JSON object.
+   * @returns {Map<string, object>}
    */
   loadCommandsFromManifest(manifest) {
     let commands = new Map();
@@ -104,8 +106,8 @@ CommandList.prototype = {
    * emits a command event with the provided name when fired.
    *
    * @param {Document} doc The XUL document.
-   * @param {String} name The name of the command.
-   * @param {String} shortcut The shortcut provided in the manifest.
+   * @param {string} name The name of the command.
+   * @param {string} shortcut The shortcut provided in the manifest.
    * @see https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XUL/key
    *
    * @returns {Document} The newly created Key element.
@@ -137,8 +139,7 @@ CommandList.prototype = {
    * Builds a XUL Key element from the provided shortcut.
    *
    * @param {Document} doc The XUL document.
-   * @param {String} name The name of the command.
-   * @param {String} shortcut The shortcut provided in the manifest.
+   * @param {string} shortcut The shortcut provided in the manifest.
    *
    * @see https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XUL/key
    * @returns {Document} The newly created Key element.
@@ -174,8 +175,8 @@ CommandList.prototype = {
    *    "PageUP"  |  "VK_PAGE_UP"
    *    "Delete"  |  "VK_DELETE"
    *
-   * @param {String} key The chrome key (e.g. "PageUp", "Space", ...)
-   * @return The constructed value for the Key's 'keycode' attribute.
+   * @param {string} chromeKey The chrome key (e.g. "PageUp", "Space", ...)
+   * @returns {string} The constructed value for the Key's 'keycode' attribute.
    */
   getKeycodeAttribute(chromeKey) {
     return `VK${chromeKey.replace(/([A-Z])/g, "_$&").toUpperCase()}`;
@@ -192,7 +193,7 @@ CommandList.prototype = {
    *    ["MacCtrl"]       |   "control"
    *
    * @param {Array} chromeModifiers The array of chrome modifiers.
-   * @return The constructed value for the Key's 'modifiers' attribute.
+   * @returns {string} The constructed value for the Key's 'modifiers' attribute.
    */
   getModifiersAttribute(chromeModifiers) {
     let modifiersMap = {

browser/components/extensions/ext-pageAction.js

@@ -134,6 +134,8 @@ PageAction.prototype = {
    * if it were clicked by a user.
    *
    * This has no effect if the page action is hidden for the selected tab.
+   *
+   * @param {Window} window
    */
   triggerAction(window) {
     let pageAction = pageActionMap.get(this.extension);

browser/components/extensions/test/browser/browser_ext_tabs_onHighlighted.js

@@ -36,6 +36,10 @@ add_task(function* testTabEvents() {
     /**
      * Asserts that the expected events are fired for the tab with id = tabId.
      * The events associated to the specified tab are removed after this check is made.
+     *
+     * @param {number} tabId
+     * @param {Array<string>} expectedEvents
+     * @returns {Promise}
      */
     function expectEvents(tabId, expectedEvents) {
       browser.test.log(`Expecting events: ${expectedEvents.join(", ")}`);
@@ -55,6 +59,9 @@ add_task(function* testTabEvents() {
 
     /**
      * Opens a new tab and asserts that the correct events are fired.
+     *
+     * @param {number} windowId
+     * @returns {Promise}
      */
     function openTab(windowId) {
       return browser.tabs.create({windowId}).then(tab => {
@@ -69,6 +76,9 @@ add_task(function* testTabEvents() {
 
     /**
      * Highlights an existing tab and asserts that the correct events are fired.
+     *
+     * @param {number} tabId
+     * @returns {Promise}
      */
     function highlightTab(tabId) {
       browser.test.log(`Highlighting tab ${tabId}`);

toolkit/components/extensions/.eslintrc

@@ -35,6 +35,21 @@
     "mozilla/no-cpows-in-tests": 1,
     "mozilla/var-only-at-top-level": 1,
 
+    "valid-jsdoc": [2, {
+      "prefer": {
+        "return": "returns",
+      },
+      "preferType": {
+        "Boolean": "boolean",
+        "Number": "number",
+        "String": "string",
+        "bool": "boolean",
+      },
+      "requireParamDescription": false,
+      "requireReturn": false,
+      "requireReturnDescription": false,
+    }],
+
     // Braces only needed for multi-line arrow function blocks
     // "arrow-body-style": [2, "as-needed"],
 
@@ -446,9 +461,6 @@
     // Require "use strict" to be defined globally in the script.
     "strict": [2, "global"],
 
-    // Warn about invalid JSDoc comments.
-    "valid-jsdoc": 0,
-
     // Allow vars to be declared anywhere in the scope.
     "vars-on-top": 0,
 

toolkit/components/extensions/Extension.jsm

@@ -1078,6 +1078,10 @@ this.Extension = function(addonData) {
  *
  * The generated extension is stored in the system temporary directory,
  * and an nsIFile object pointing to it is returned.
+ *
+ * @param {string} id
+ * @param {object} data
+ * @returns {nsIFile}
  */
 this.Extension.generateXPI = function(id, data) {
   let manifest = data.manifest;
@@ -1171,6 +1175,10 @@ this.Extension.generateXPI = function(id, data) {
  * A skeleton Extension-like object, used for testing, which installs an
  * add-on via the add-on manager when startup() is called, and
  * uninstalles it on shutdown().
+ *
+ * @param {string} id
+ * @param {nsIFile} file
+ * @param {nsIURI} rootURI
  */
 function MockExtension(id, file, rootURI) {
   this.id = id;
@@ -1229,6 +1237,10 @@ MockExtension.prototype = {
 /**
  * Generates a new extension using |Extension.generateXPI|, and initializes a
  * new |Extension| instance which will execute it.
+ *
+ * @param {string} id
+ * @param {object} data
+ * @returns {Extension}
  */
 this.Extension.generate = function(id, data) {
   let file = this.generateXPI(id, data);

toolkit/components/extensions/ExtensionStorage.jsm

@@ -68,6 +68,13 @@ this.ExtensionStorage = {
   /**
    * Sanitizes the given value, and returns a JSON-compatible
    * representation of it, based on the privileges of the given global.
+   *
+   * @param {value} value
+   *        The value to sanitize.
+   * @param {object} global
+   *        The global for which to sanitize the value.
+   * @returns {value}
+   *        The sanitized value.
    */
   sanitize(value, global) {
     // We can't trust that the global has privileges to access this

toolkit/components/extensions/ExtensionUtils.jsm

@@ -208,6 +208,15 @@ class BaseContext {
    * A wrapper around MessageChannel.sendMessage which adds the extension ID
    * to the recipient object, and ensures replies are not processed after the
    * context has been unloaded.
+   *
+   * @param {nsIMessageManager} target
+   * @param {string} messageName
+   * @param {object} data
+   * @param {object} [options]
+   * @param {object} [options.sender]
+   * @param {object} [options.recipient]
+   *
+   * @returns {Promise}
    */
   sendMessage(target, messageName, data, options = {}) {
     options.recipient = options.recipient || {};
@@ -238,6 +247,9 @@ class BaseContext {
    * scope. If it is an Error object which does *not* belong to the
    * clone scope, it is reported, and converted to an unexpected
    * exception error.
+   *
+   * @param {Error|object} error
+   * @returns {Error}
    */
   normalizeError(error) {
     if (error instanceof this.cloneScope.Error) {

toolkit/components/extensions/MessageChannel.jsm

@@ -138,6 +138,7 @@ class FilteringMessageManager {
    *        data:
    *          An object describing the message, as defined in
    *          `MessageChannel.addListener`.
+   * @param {nsIMessageManager} messageManager
    */
   constructor(messageName, callback, messageManager) {
     this.messageName = messageName;
@@ -351,7 +352,7 @@ this.MessageChannel = {
    *    corresponding property in `data` with the same value. If
    *    false, properties present in both objects must have the same
    *    balue.
-   * @returns {bool} True if the objects match.
+   * @returns {boolean} True if the objects match.
    */
   matchesFilter(filter, data, strict = true) {
     if (strict) {
@@ -429,8 +430,7 @@ this.MessageChannel = {
   /**
    * Removes a message listener from the given message manager.
    *
-   * @param {nsIMessageSender} target
-   * @param {nsIMessageSender|[nsIMessageSender]} targets
+   * @param {nsIMessageSender|Array<nsIMessageSender>} targets
    *    The message managers on which to stop listening.
    * @param {string|number} messageName
    *    The name of the message to stop listening for.
@@ -474,7 +474,7 @@ this.MessageChannel = {
    * @param {integer} [options.responseType=RESPONSE_SINGLE]
    *    Specifies the type of response expected. See the `RESPONSE_*`
    *    contents for details.
-   * @returns Promise
+   * @returns {Promise}
    */
   sendMessage(target, messageName, data, options = {}) {
     let sender = options.sender || {};
@@ -560,6 +560,10 @@ this.MessageChannel = {
    *
    * Each handler object is a `MessageReceiver` object as passed to
    * `addListener`.
+   *
+   * @param {Array<MessageHandler>} handlers
+   * @param {object} data
+   * @param {nsIMessageSender|nsIMessageManagerOwner} data.target
    */
   _handleMessage(handlers, data) {
     // The target passed to `receiveMessage` is sometimes a message manager
@@ -622,6 +626,10 @@ this.MessageChannel = {
    *
    * Each handler object is a deferred object created by `sendMessage`, and
    * should be resolved or rejected based on the contents of the response.
+   *
+   * @param {Array<MessageHandler>} handlers
+   * @param {object} data
+   * @param {nsIMessageSender|nsIMessageManagerOwner} data.target
    */
   _handleResponse(handlers, data) {
     // If we have an error at this point, we have handler to report it to,
@@ -662,6 +670,8 @@ this.MessageChannel = {
    *
    * These values are used to clear pending responses when execution
    * contexts are destroyed.
+   *
+   * @param {Deferred} deferred
    */
   _addPendingResponse(deferred) {
     let cleanup = () => {

toolkit/components/extensions/Schemas.jsm

@@ -145,6 +145,9 @@ class Context {
    *
    * If the context has a `currentTarget` value, this is prepended to
    * the message to indicate the location of the error.
+   *
+   * @param {string} message
+   * @returns {object}
    */
   error(message) {
     if (this.currentTarget) {
@@ -160,6 +163,9 @@ class Context {
    *
    * If the context has a `currentTarget` value, this is prepended to
    * the message, in the same way as for the `error` method.
+   *
+   * @param {string} message
+   * @returns {Error}
    */
   makeError(message) {
     let {error} = this.error(message);
@@ -172,6 +178,8 @@ class Context {
   /**
    * Logs the given error to the console. May be overridden to enable
    * custom logging.
+   *
+   * @param {Error|string} error
    */
   logError(error) {
     Cu.reportError(error);
@@ -198,6 +206,10 @@ class Context {
    *
    * This is used to identify the path of the property being processed
    * when reporting type errors.
+   *
+   * @param {string} component
+   * @param {function} callback
+   * @returns {*}
    */
   withPath(component, callback) {
     this.path.push(component);
@@ -309,6 +321,7 @@ class Entry {
     }
 
     /**
+     * @property {string} [preprocessor]
      * If set to a string value, and a preprocessor of the same is
      * defined in the validation context, it will be applied to this
      * value prior to any normalization.
@@ -319,6 +332,10 @@ class Entry {
   /**
    * Preprocess the given value with the preprocessor declared in
    * `preprocessor`.
+   *
+   * @param {*} value
+   * @param {Context} context
+   * @returns {*}
    */
   preprocess(value, context) {
     if (this.preprocessor) {
@@ -330,6 +347,9 @@ class Entry {
   /**
    * Logs a deprecation warning for this entry, based on the value of
    * its `deprecated` property.
+   *
+   * @param {Context} context
+   * @param {value} [value]
    */
   logDeprecation(context, value = null) {
     let message = "This property is deprecated";
@@ -351,6 +371,9 @@ class Entry {
   /**
    * Checks whether the entry is deprecated and, if so, logs a
    * deprecation message.
+   *
+   * @param {Context} context
+   * @param {value} [value]
    */
   checkDeprecated(context, value = null) {
     if (this.deprecated) {

toolkit/components/extensions/test/mochitest/test_ext_content_security_policy.html

@@ -18,6 +18,8 @@
  * documents that belong to it. This tests both the base policies and add-on
  * specific policies, and ensures that the parsed policies applied to the
  * document's principal match what was specified in the policy string.
+ *
+ * @param {object} [customCSP]
  */
 function* testPolicy(customCSP = null) {
   let baseURL;

toolkit/modules/addons/WebNavigation.jsm

@@ -85,35 +85,41 @@ var Manager = {
   },
 
   /**
-   *  Support nsIObserver interface to observe the urlbar autocomplete events used
-   *  to keep track of the urlbar user interaction.
+   * Support nsIObserver interface to observe the urlbar autocomplete events used
+   * to keep track of the urlbar user interaction.
    */
   QueryInterface: XPCOMUtils.generateQI([Ci.nsIObserver, Ci.nsISupportsWeakReference]),
 
   /**
-   *  Observe autocomplete-did-enter-text topic to track the user interaction with
-   *  the awesome bar.
+   * Observe autocomplete-did-enter-text topic to track the user interaction with
+   * the awesome bar.
+   *
+   * @param {nsIAutoCompleteInput} subject
+   * @param {string} topic
+   * @param {string} data
    */
   observe: function(subject, topic, data) {
     if (topic == "autocomplete-did-enter-text") {
-      this.onURLBarAutoCompletion(subject, topic, data);
+      this.onURLBarAutoCompletion(subject);
     }
   },
 
   /**
-   *  Recognize the type of urlbar user interaction (e.g. typing a new url,
-   *  clicking on an url generated from a searchengine or a keyword, or a
-   *  bookmark found by the urlbar autocompletion).
+   * Recognize the type of urlbar user interaction (e.g. typing a new url,
+   * clicking on an url generated from a searchengine or a keyword, or a
+   * bookmark found by the urlbar autocompletion).
+   *
+   * @param {nsIAutoCompleteInput} input
    */
-  onURLBarAutoCompletion(subject, topic, data) {
-    if (subject && subject instanceof Ci.nsIAutoCompleteInput) {
+  onURLBarAutoCompletion(input) {
+    if (input && input instanceof Ci.nsIAutoCompleteInput) {
       // We are only interested in urlbar autocompletion events
-      if (subject.id !== "urlbar") {
+      if (input.id !== "urlbar") {
         return;
       }
 
-      let controller = subject.popup.view.QueryInterface(Ci.nsIAutoCompleteController);
-      let idx = subject.popup.selectedIndex;
+      let controller = input.popup.view.QueryInterface(Ci.nsIAutoCompleteController);
+      let idx = input.popup.selectedIndex;
 
       let tabTransistionData = {
         from_address_bar: true,
@@ -124,7 +130,7 @@ var Manager = {
         tabTransistionData.typed = true;
       } else {
         let value = controller.getValueAt(idx);
-        let action = subject._parseActionUrl(value);
+        let action = input._parseActionUrl(value);
 
         if (action) {
           // Detect keywork and generated and more typed scenarios.
@@ -174,8 +180,16 @@ var Manager = {
   },
 
   /**
-   *  Keep track of a recent user interaction and cache it in a
-   *  map associated to the current selected tab.
+   * Keep track of a recent user interaction and cache it in a
+   * map associated to the current selected tab.
+   *
+   * @param {object} tabTransitionData
+   * @param {boolean} [tabTransitionData.auto_bookmark]
+   * @param {boolean} [tabTransitionData.from_address_bar]
+   * @param {boolean} [tabTransitionData.generated]
+   * @param {boolean} [tabTransitionData.keyword]
+   * @param {boolean} [tabTransitionData.link]
+   * @param {boolean} [tabTransitionData.typed]
    */
   setRecentTabTransitionData(tabTransitionData) {
     let window = RecentWindow.getMostRecentBrowserWindow();
@@ -196,13 +210,16 @@ var Manager = {
   },
 
   /**
-   *  Retrieve recent data related to a recent user interaction give a
-   *  given tab's linkedBrowser (only if is is more recent than the
-   *  `RECENT_DATA_THRESHOLD`).
+   * Retrieve recent data related to a recent user interaction give a
+   * given tab's linkedBrowser (only if is is more recent than the
+   * `RECENT_DATA_THRESHOLD`).
    *
-   *  NOTE: this method is used to retrieve the tab transition data
-   *  collected when one of the `onCommitted`, `onHistoryStateUpdated`
-   *  or `onReferenceFragmentUpdated` events has been received.
+   * NOTE: this method is used to retrieve the tab transition data
+   * collected when one of the `onCommitted`, `onHistoryStateUpdated`
+   * or `onReferenceFragmentUpdated` events has been received.
+   *
+   * @param {XULBrowserElement} browser
+   * @returns {object}
    */
   getAndForgetRecentTabTransitionData(browser) {
     let data = this.recentTabTransitionData.get(browser);
@@ -218,8 +235,8 @@ var Manager = {
   },
 
   /**
-   *  Receive messages from the WebNavigationContent.js framescript
-   *  over message manager events.
+   * Receive messages from the WebNavigationContent.js framescript
+   * over message manager events.
    */
   receiveMessage({name, data, target}) {
     switch (name) {

toolkit/modules/addons/WebNavigationFrames.jsm

@@ -24,7 +24,7 @@ function getParentWindowId(window) {
  * Retrieve the DOMWindow associated to the docShell passed as parameter.
  *
  * @param    {nsIDocShell}  docShell - the docShell that we want to get the DOMWindow from.
- * @return   {nsIDOMWindow}          - the DOMWindow associated to the docShell.
+ * @returns  {nsIDOMWindow}          - the DOMWindow associated to the docShell.
  */
 function docShellToWindow(docShell) {
   return docShell.QueryInterface(Ci.nsIInterfaceRequestor)
@@ -47,7 +47,7 @@ function docShellToWindow(docShell) {
  * Convert a docShell object into its internal FrameDetail representation.
  *
  * @param    {nsIDocShell} docShell - the docShell object to be converted into a FrameDetail JSON object.
- * @return   {FrameDetail} the FrameDetail JSON object which represents the docShell.
+ * @returns  {FrameDetail} the FrameDetail JSON object which represents the docShell.
  */
 function convertDocShellToFrameDetail(docShell) {
   let window = docShellToWindow(docShell);
@@ -62,8 +62,8 @@ function convertDocShellToFrameDetail(docShell) {
 /**
  * A generator function which iterates over a docShell tree, given a root docShell.
  *
- * @param  {nsIDocShell} docShell - the root docShell object
- * @return {Iterator<DocShell>} the FrameDetail JSON object which represents the docShell.
+ * @param   {nsIDocShell} docShell - the root docShell object
+ * @returns {Iterator<DocShell>} the FrameDetail JSON object which represents the docShell.
  */
 function* iterateDocShellTree(docShell) {
   let docShellsEnum = docShell.getDocShellEnumerator(
@@ -104,9 +104,9 @@ function getFrameId(window) {
  *
  * @param  {number}      frameId - the frame ID of the frame to retrieve, as
  *                                 described in getFrameId.
- * @param  {nsIDocShell} docShell - the root docShell object
- * @return {nsIDocShell?} the docShell with the given frameId, or null
- *                        if no match.
+ * @param   {nsIDocShell} rootDocShell - the root docShell object
+ * @returns {nsIDocShell?} the docShell with the given frameId, or null
+ *                         if no match.
  */
 function findDocShell(frameId, rootDocShell) {
   for (let docShell of iterateDocShellTree(rootDocShell)) {