Bug 1559355 - Add jsdoc to public methods of custom elements. r=Gijs
authorJared Wein <jwein@mozilla.com>
Tue, 18 Jun 2019 23:34:16 +0000
changeset 479152 5ff49a14d8d33f6d43bb1e81f3e26f3815a5041e
parent 479151 e778be2565a3c0d464c6ff66e1661e1f3d74a473
child 479153 c5293d04b409f0c4d57ed5ad9fba73f75d59e48a
push id36170
push usercbrindusan@mozilla.com
push dateWed, 19 Jun 2019 03:56:45 +0000
treeherdermozilla-central@5f0f37756053 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersGijs
bugs1559355
milestone69.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1559355 - Add jsdoc to public methods of custom elements. r=Gijs Differential Revision: https://phabricator.services.mozilla.com/D35112
browser/components/aboutlogins/content/components/copy-to-clipboard-button.js
browser/components/aboutlogins/content/components/login-item.js
browser/components/aboutlogins/content/components/login-list-item.js
browser/components/aboutlogins/content/components/login-list.js
browser/components/aboutlogins/content/components/menu-button.js
browser/components/aboutlogins/content/components/reflected-fluent-element.js
--- a/browser/components/aboutlogins/content/components/copy-to-clipboard-button.js
+++ b/browser/components/aboutlogins/content/components/copy-to-clipboard-button.js
@@ -1,16 +1,20 @@
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 import {recordTelemetryEvent} from "../aboutLoginsUtils.js";
 import ReflectedFluentElement from "./reflected-fluent-element.js";
 
 export default class CopyToClipboardButton extends ReflectedFluentElement {
+  /**
+   * The number of milliseconds to display the "Copied" success message
+   * before reverting to the normal "Copy" button.
+   */
   static get BUTTON_RESET_TIMEOUT() {
     return 5000;
   }
 
   constructor() {
     super();
 
     this._relatedInput = null;
@@ -62,13 +66,17 @@ export default class CopyToClipboardButt
       }, CopyToClipboardButton.BUTTON_RESET_TIMEOUT);
     }, () => copyButton.disabled = false);
 
     if (this.dataset.telemetryObject) {
       recordTelemetryEvent({object: this.dataset.telemetryObject, method: "copy"});
     }
   }
 
+  /**
+   * @param {Element} val A reference to the input element whose value will
+   *                      be placed on the clipboard.
+   */
   set relatedInput(val) {
     this._relatedInput = val;
   }
 }
 customElements.define("copy-to-clipboard-button", CopyToClipboardButton);
--- a/browser/components/aboutlogins/content/components/login-item.js
+++ b/browser/components/aboutlogins/content/components/login-item.js
@@ -233,62 +233,93 @@ export default class LoginItem extends R
             recordTelemetryEvent({object: "new_login", method: "save"});
           }
         }
         break;
       }
     }
   }
 
+  /**
+   * @param {login} login The login that should be displayed. The login object is
+   *                      a plain JS object representation of nsILoginInfo/nsILoginMetaInfo.
+   */
   setLogin(login) {
     this._login = login;
 
     let form = this.shadowRoot.querySelector("form");
     form.reset();
 
     this.toggleAttribute("isNewLogin", !login.guid);
     this.toggleEditing(!login.guid);
 
     let revealCheckbox = this.shadowRoot.querySelector(".reveal-password-checkbox");
     revealCheckbox.checked = false;
 
     this.render();
   }
 
+  /**
+   * Updates the view if the login argument matches the login currently
+   * displayed.
+   *
+   * @param {login} login The login that was added to storage. The login object is
+   *                      a plain JS object representation of nsILoginInfo/nsILoginMetaInfo.
+   */
   loginAdded(login) {
     if (this._login.guid ||
         !window.AboutLoginsUtils.doLoginsMatch(login, this._loginFromForm())) {
       return;
     }
 
     this.toggleEditing(false);
     this._login = login;
     this.render();
   }
 
+  /**
+   * Updates the view if the login argument matches the login currently
+   * displayed.
+   *
+   * @param {login} login The login that was modified in storage. The login object is
+   *                      a plain JS object representation of nsILoginInfo/nsILoginMetaInfo.
+   */
   loginModified(login) {
     if (this._login.guid != login.guid) {
       return;
     }
 
     this.toggleEditing(false);
     this._login = login;
     this.render();
   }
 
+  /**
+   * Clears the displayed login if the argument matches the currently
+   * displayed login.
+   *
+   * @param {login} login The login that was removed from storage. The login object is
+   *                      a plain JS object representation of nsILoginInfo/nsILoginMetaInfo.
+   */
   loginRemoved(login) {
     if (login.guid != this._login.guid) {
       return;
     }
 
     this.toggleEditing(false);
     this._login = {};
     this.render();
   }
 
+  /**
+   * Toggles the login-item view from editing to non-editing mode.
+   *
+   * @param {boolean} force When true puts the form in 'edit' mode, otherwise
+   *                        puts the form in read-only mode.
+   */
   toggleEditing(force) {
     let shouldEdit = force !== undefined ? force : !this.hasAttribute("editing");
 
     if (!shouldEdit) {
       this.removeAttribute("isNewLogin");
     }
 
     if (shouldEdit) {
--- a/browser/components/aboutlogins/content/components/login-list-item.js
+++ b/browser/components/aboutlogins/content/components/login-list-item.js
@@ -49,14 +49,20 @@ export default class LoginListItem exten
           detail: this._login,
         }));
 
         recordTelemetryEvent({object: "existing_login", method: "select"});
       }
     }
   }
 
+  /**
+   * Updates the cached login object with new values.
+   *
+   * @param {login} login The login object to display. The login object is
+   *                      a plain JS object representation of nsILoginInfo/nsILoginMetaInfo.
+   */
   update(login) {
     this._login = login;
     this.render();
   }
 }
 customElements.define("login-list-item", LoginListItem);
--- a/browser/components/aboutlogins/content/components/login-list.js
+++ b/browser/components/aboutlogins/content/components/login-list.js
@@ -61,16 +61,20 @@ export default class LoginList extends R
       }
       list.append(listItem);
     }
 
     let visibleLoginCount = this._applyFilter();
     document.l10n.setAttributes(this, "login-list", {count: visibleLoginCount});
   }
 
+  /**
+   * Filters the displayed logins in the list to only those matching the
+   * cached filter value.
+   */
   _applyFilter() {
     let matchingLoginGuids;
     if (this._filter) {
       matchingLoginGuids = this._logins.filter(login => {
         return login.origin.toLocaleLowerCase().includes(this._filter) ||
                login.username.toLocaleLowerCase().includes(this._filter);
       }).map(login => login.guid);
     } else {
@@ -145,34 +149,49 @@ export default class LoginList extends R
         break;
       }
       default:
         return false;
     }
     return true;
   }
 
+  /**
+   * @param {login[]} logins An array of logins used for displaying in the list.
+   */
   setLogins(logins) {
     this._logins = logins;
     this.render();
   }
 
+  /**
+   * @param {login} login A login that was added to storage.
+   */
   loginAdded(login) {
     this._logins.push(login);
     this.render();
   }
 
+  /**
+   * @param {login} login A login that was modified in storage. The related login-list-item
+   *                       will get updated.
+   */
   loginModified(login) {
     for (let i = 0; i < this._logins.length; i++) {
       if (this._logins[i].guid == login.guid) {
         this._logins[i] = login;
         break;
       }
     }
     this.render();
   }
 
+  /**
+   * @param {login} login A login that was removed from storage. The related login-list-item
+   *                      will get removed. The login object is a plain JS object
+   *                      representation of nsILoginInfo/nsILoginMetaInfo.
+   */
   loginRemoved(login) {
     this._logins = this._logins.filter(l => l.guid != login.guid);
     this.render();
   }
 }
 customElements.define("login-list", LoginList);
--- a/browser/components/aboutlogins/content/components/menu-button.js
+++ b/browser/components/aboutlogins/content/components/menu-button.js
@@ -68,16 +68,19 @@ export default class MenuButton extends 
           break;
         }
         this.toggleMenu();
         break;
       }
     }
   }
 
+  /**
+   * Toggles the visibility of the menu.
+   */
   toggleMenu() {
     let wasHidden = this.shadowRoot.querySelector(".menu").hidden;
     if (wasHidden) {
       this.showMenu();
     } else {
       this.hideMenu();
     }
   }
--- a/browser/components/aboutlogins/content/components/reflected-fluent-element.js
+++ b/browser/components/aboutlogins/content/components/reflected-fluent-element.js
@@ -2,18 +2,20 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 
 export default class ReflectedFluentElement extends HTMLElement {
   _isReflectedAttributePresent(attr) {
     return this.constructor.reflectedFluentIDs.includes(attr.name);
   }
 
-  /* This function should be called to apply any localized strings that Fluent
-     may have applied to the element before the custom element was defined. */
+  /*
+   * Called to apply any localized strings that Fluent may have applied
+   * to the element before the custom element was defined.
+   */
   reflectFluentStrings() {
     for (let reflectedFluentID of this.constructor.reflectedFluentIDs) {
       if (this.hasAttribute(reflectedFluentID)) {
         if (this.handleSpecialCaseFluentString &&
             this.handleSpecialCaseFluentString(reflectedFluentID)) {
           continue;
         }
 
@@ -21,18 +23,20 @@ export default class ReflectedFluentElem
         // Strings that are reflected to their shadowed element are assigned
         // to an attribute name that matches a className on the element.
         let shadowedElement = this.shadowRoot.querySelector("." + reflectedFluentID);
         shadowedElement.textContent = attrValue;
       }
     }
   }
 
-  /* Fluent doesn't handle localizing into Shadow DOM yet so strings
-     need to get reflected in to their targeted element. */
+  /*
+   * Fluent doesn't handle localizing into Shadow DOM yet so strings
+   * need to get reflected in to their targeted element.
+   */
   attributeChangedCallback(attr, oldValue, newValue) {
     if (!this.shadowRoot) {
       return;
     }
 
     // Don't respond to attribute changes that aren't related to locale text.
     if (!this.constructor.reflectedFluentIDs.includes(attr)) {
       return;