Bug 1559355 - Add jsdoc to public methods of custom elements. r=Gijs

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

--HG--
extra : moz-landing-system : lando

browser/components/aboutlogins/content/components/copy-to-clipboard-button.js

@@ -6,6 +6,10 @@ 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;
   }
@@ -67,6 +71,10 @@ export default class CopyToClipboardButton extends ReflectedFluentElement {
     }
   }
 
+  /**
+   * @param {Element} val A reference to the input element whose value will
+   *                      be placed on the clipboard.
+   */
   set relatedInput(val) {
     this._relatedInput = val;
   }

browser/components/aboutlogins/content/components/login-item.js

@@ -238,6 +238,10 @@ export default class LoginItem extends ReflectedFluentElement {
     }
   }
 
+  /**
+   * @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;
 
@@ -253,6 +257,13 @@ export default class LoginItem extends ReflectedFluentElement {
     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())) {
@@ -264,6 +275,13 @@ export default class LoginItem extends ReflectedFluentElement {
     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;
@@ -274,6 +292,13 @@ export default class LoginItem extends ReflectedFluentElement {
     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;
@@ -284,6 +309,12 @@ export default class LoginItem extends ReflectedFluentElement {
     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");
 

browser/components/aboutlogins/content/components/login-list-item.js

@@ -54,6 +54,12 @@ export default class LoginListItem extends HTMLElement {
     }
   }
 
+  /**
+   * 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();

browser/components/aboutlogins/content/components/login-list.js

@@ -66,6 +66,10 @@ export default class LoginList extends ReflectedFluentElement {
     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) {
@@ -150,16 +154,26 @@ export default class LoginList extends ReflectedFluentElement {
     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) {
@@ -170,6 +184,11 @@ export default class LoginList extends ReflectedFluentElement {
     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();

browser/components/aboutlogins/content/components/menu-button.js

@@ -73,6 +73,9 @@ export default class MenuButton extends ReflectedFluentElement {
     }
   }
 
+  /**
+   * Toggles the visibility of the menu.
+   */
   toggleMenu() {
     let wasHidden = this.shadowRoot.querySelector(".menu").hidden;
     if (wasHidden) {

browser/components/aboutlogins/content/components/reflected-fluent-element.js

@@ -7,8 +7,10 @@ export default class ReflectedFluentElement extends HTMLElement {
     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)) {
@@ -26,8 +28,10 @@ export default class ReflectedFluentElement extends HTMLElement {
     }
   }
 
-  /* 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;