Bug 1127579 - Cleanup jsdoc comments in nsLoginManagerPrompter.js a=gchang
authorMatthew Noorenberghe <mozilla@noorenberghe.ca>
Wed, 27 Jul 2016 13:28:06 -0700
changeset 340043 dc272cf9d820263c646fc42f6354b55203019e3b
parent 340042 01e60d85a78c0266d2bfbde530f91a2c6c54fecc
child 340044 3fc2b0d8fb83ae4b91db21ad61998008965dcc8b
push id6249
push userjlund@mozilla.com
push dateMon, 01 Aug 2016 13:59:36 +0000
treeherdermozilla-beta@bad9d4f5bf7e [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersgchang
bugs1127579
milestone49.0a2
Bug 1127579 - Cleanup jsdoc comments in nsLoginManagerPrompter.js a=gchang MozReview-Commit-ID: 5VzE9DyFZEb
toolkit/components/passwordmgr/nsLoginManagerPrompter.js
--- a/toolkit/components/passwordmgr/nsLoginManagerPrompter.js
+++ b/toolkit/components/passwordmgr/nsLoginManagerPrompter.js
@@ -22,19 +22,17 @@ const BRAND_BUNDLE = "chrome://branding/
  * Constants for password prompt telemetry.
  * Mirrored in mobile/android/components/LoginManagerPrompter.js */
 const PROMPT_DISPLAYED = 0;
 
 const PROMPT_ADD_OR_UPDATE = 1;
 const PROMPT_NOTNOW = 2;
 const PROMPT_NEVER = 3;
 
-/*
- * LoginManagerPromptFactory
- *
+/**
  * Implements nsIPromptFactory
  *
  * Invoked by [toolkit/components/prompts/src/nsPrompter.js]
  */
 function LoginManagerPromptFactory() {
   Services.obs.addObserver(this, "quit-application-granted", true);
   Services.obs.addObserver(this, "passwordmgr-crypto-login", true);
   Services.obs.addObserver(this, "passwordmgr-crypto-loginCanceled", true);
@@ -181,19 +179,17 @@ XPCOMUtils.defineLazyGetter(this.LoginMa
 
 
 
 /* ==================== LoginManagerPrompter ==================== */
 
 
 
 
-/*
- * LoginManagerPrompter
- *
+/**
  * Implements interfaces for prompting the user to enter/save/change auth info.
  *
  * nsIAuthPrompt: Used by SeaMonkey, Thunderbird, but not Firefox.
  *
  * nsIAuthPrompt2: Is invoked by a channel for protocol-based authentication
  * (eg HTTP Authenticate, FTP login).
  *
  * nsILoginManagerPrompter: Used by Login Manager for saving/changing logins
@@ -274,19 +270,17 @@ LoginManagerPrompter.prototype = {
   },
 
 
 
 
   /* ---------- nsIAuthPrompt prompts ---------- */
 
 
-  /*
-   * prompt
-   *
+  /**
    * Wrapper around the prompt service prompt. Saving random fields here
    * doesn't really make sense and therefore isn't implemented.
    */
   prompt : function (aDialogTitle, aText, aPasswordRealm,
                      aSavePassword, aDefaultText, aResult) {
     if (aSavePassword != Ci.nsIAuthPrompt.SAVE_PASSWORD_NEVER)
       throw new Components.Exception("prompt only supports SAVE_PASSWORD_NEVER",
                                      Cr.NS_ERROR_NOT_IMPLEMENTED);
@@ -297,19 +291,17 @@ LoginManagerPrompter.prototype = {
       aResult.value = aDefaultText;
     }
 
     return this._promptService.prompt(this._window,
            aDialogTitle, aText, aResult, null, {});
   },
 
 
-  /*
-   * promptUsernameAndPassword
-   *
+  /**
    * Looks up a username and password in the database. Will prompt the user
    * with a dialog, even if a username and password are found.
    */
   promptUsernameAndPassword : function (aDialogTitle, aText, aPasswordRealm,
                                        aSavePassword, aUsername, aPassword) {
     this.log("===== promptUsernameAndPassword() called =====");
 
     if (aSavePassword == Ci.nsIAuthPrompt.SAVE_PASSWORD_FOR_SESSION)
@@ -396,19 +388,17 @@ LoginManagerPrompter.prototype = {
       this.log("Login unchanged, no further action needed.");
       this._updateLogin(selectedLogin);
     }
 
     return ok;
   },
 
 
-  /*
-   * promptPassword
-   *
+  /**
    * If a password is found in the database for the password realm, it is
    * returned straight away without displaying a dialog.
    *
    * If a password is not found in the database, the user will be prompted
    * with a dialog with a text field and ok/cancel buttons. If the user
    * allows it, then the password will be saved in the database.
    */
   promptPassword : function (aDialogTitle, aText, aPasswordRealm,
@@ -503,24 +493,22 @@ LoginManagerPrompter.prototype = {
     return [formattedHostname, formattedHostname + pathname, uri.username];
   },
 
   /* ---------- nsIAuthPrompt2 prompts ---------- */
 
 
 
 
-  /*
-   * promptAuth
-   *
+  /**
    * Implementation of nsIAuthPrompt2.
    *
-   * nsIChannel aChannel
-   * int        aLevel
-   * nsIAuthInformation aAuthInfo
+   * @param {nsIChannel} aChannel
+   * @param {int}        aLevel
+   * @param {nsIAuthInformation} aAuthInfo
    */
   promptAuth : function (aChannel, aLevel, aAuthInfo) {
     var selectedLogin = null;
     var checkbox = { value : false };
     var checkboxLabel = null;
     var epicfail = false;
     var canAutologin = false;
 
@@ -689,57 +677,43 @@ LoginManagerPrompter.prototype = {
 
 
 
 
   /* ---------- nsILoginManagerPrompter prompts ---------- */
 
 
 
-
-  /*
-   * init
-   *
-   */
   init : function (aWindow, aFactory) {
     this._window = aWindow;
     this._factory = aFactory || null;
     this._browser = null;
     this._opener = null;
 
     this.log("===== initialized =====");
   },
 
   setE10sData : function (aBrowser, aOpener) {
     if (!(this._window instanceof Ci.nsIDOMChromeWindow))
       throw new Error("Unexpected call");
     this._browser = aBrowser;
     this._opener = aOpener;
   },
 
-
-  /*
-   * promptToSavePassword
-   *
-   */
   promptToSavePassword : function (aLogin) {
     this.log("promptToSavePassword");
     var notifyObj = this._getPopupNote() || this._getNotifyBox();
     if (notifyObj)
       this._showSaveLoginNotification(notifyObj, aLogin);
     else
       this._showSaveLoginDialog(aLogin);
   },
 
-
-  /*
-   * _showLoginNotification
-   *
+  /**
    * Displays a notification bar.
-   *
    */
   _showLoginNotification : function (aNotifyBox, aName, aText, aButtons) {
     var oldBar = aNotifyBox.getNotificationWithValue(aName);
     const priority = aNotifyBox.PRIORITY_INFO_MEDIUM;
 
     this.log("Adding new " + aName + " notification bar");
     var newBar = aNotifyBox.appendNotification(
                             aText, aName,
@@ -1080,21 +1054,16 @@ LoginManagerPrompter.prototype = {
         }
       ];
 
       this._showLoginNotification(aNotifyObj, "password-save",
                                   notificationText, buttons);
     }
   },
 
-
-  /*
-   * _removeLoginNotifications
-   *
-   */
   _removeLoginNotifications : function () {
     var popupNote = this._getPopupNote();
     if (popupNote)
       popupNote = popupNote.getNotification("password");
     if (popupNote)
       popupNote.remove();
 
     var notifyBox = this._getNotifyBox();
@@ -1109,22 +1078,19 @@ LoginManagerPrompter.prototype = {
       if (oldBar) {
         this.log("Removing change-password notification bar.");
         notifyBox.removeNotification(oldBar);
       }
     }
   },
 
 
-  /*
-   * _showSaveLoginDialog
-   *
+  /**
    * Called when we detect a new login in a form submission,
    * asks the user what to do.
-   *
    */
   _showSaveLoginDialog : function (aLogin) {
     const buttonFlags = Ci.nsIPrompt.BUTTON_POS_1_DEFAULT +
         (Ci.nsIPrompt.BUTTON_TITLE_IS_STRING * Ci.nsIPrompt.BUTTON_POS_0) +
         (Ci.nsIPrompt.BUTTON_TITLE_IS_STRING * Ci.nsIPrompt.BUTTON_POS_1) +
         (Ci.nsIPrompt.BUTTON_TITLE_IS_STRING * Ci.nsIPrompt.BUTTON_POS_2);
 
     var displayHost = this._getShortDisplayHost(aLogin.hostname);
@@ -1190,30 +1156,27 @@ LoginManagerPrompter.prototype = {
     if (notifyObj) {
       this._showChangeLoginNotification(notifyObj, aOldLogin,
                                         aNewLogin);
     } else {
       this._showChangeLoginDialog(aOldLogin, aNewLogin);
     }
   },
 
-  /*
-   * _showChangeLoginNotification
-   *
+  /**
    * Shows the Change Password notification bar or popup notification.
    *
    * @param aNotifyObj
    *        A notification box or a popup notification.
    *
    * @param aOldLogin
    *        The stored login we want to update.
    *
    * @param aNewLogin
    *        The login object with the changes we want to make.
-   *
    */
   _showChangeLoginNotification(aNotifyObj, aOldLogin, aNewLogin) {
     var changeButtonText =
           this._getLocalizedString("notifyBarUpdateButtonText");
     var changeButtonAccessKey =
           this._getLocalizedString("notifyBarUpdateButtonAccessKey");
 
     // We reuse the existing message, even if it expects a username, until we
@@ -1262,21 +1225,18 @@ LoginManagerPrompter.prototype = {
       ];
 
       this._showLoginNotification(aNotifyObj, "password-change",
                                   notificationText, buttons);
     }
   },
 
 
-  /*
-   * _showChangeLoginDialog
-   *
+  /**
    * Shows the Change Password dialog.
-   *
    */
   _showChangeLoginDialog(aOldLogin, aNewLogin) {
     const buttonFlags = Ci.nsIPrompt.STD_YES_NO_BUTTONS;
 
     var dialogText;
     if (aOldLogin.username)
       dialogText  = this._getLocalizedString(
                               "updatePasswordMsg",
@@ -1295,19 +1255,17 @@ LoginManagerPrompter.prototype = {
                             null, {});
     if (ok) {
       this.log("Updating password for user " + aOldLogin.username);
       this._updateLogin(aOldLogin, aNewLogin);
     }
   },
 
 
-  /*
-   * promptToChangePasswordWithUsernames
-   *
+  /**
    * Called when we detect a password change in a form submission, but we
    * don't know which existing login (username) it's for. Asks the user
    * to select a username and confirm the password change.
    *
    * Note: The caller doesn't know the username for aNewLogin, so this
    *       function fills in .username and .usernameField with the values
    *       from the login selected by the user.
    *
@@ -1365,36 +1323,31 @@ LoginManagerPrompter.prototype = {
       propBag.setProperty("timePasswordChanged", now);
     }
     propBag.setProperty("timeLastUsed", now);
     propBag.setProperty("timesUsedIncrement", 1);
     this._pwmgr.modifyLogin(login, propBag);
   },
 
 
-  /*
-   * _getChromeWindow
-   *
+  /**
    * Given a content DOM window, returns the chrome window it's in.
    */
   _getChromeWindow: function (aWindow) {
     // In e10s, aWindow may already be a chrome window.
     if (aWindow instanceof Ci.nsIDOMChromeWindow)
       return aWindow;
     var chromeWin = aWindow.QueryInterface(Ci.nsIInterfaceRequestor)
                            .getInterface(Ci.nsIWebNavigation)
                            .QueryInterface(Ci.nsIDocShell)
                            .chromeEventHandler.ownerDocument.defaultView;
     return chromeWin;
   },
 
 
-  /*
-   * _getNotifyWindow
-   */
   _getNotifyWindow: function () {
 
     try {
       // Get topmost window, in case we're in a frame.
       var notifyWin = this._window.top;
       var isE10s = (notifyWin instanceof Ci.nsIDOMChromeWindow);
       var useOpener = false;
 
@@ -1450,19 +1403,17 @@ LoginManagerPrompter.prototype = {
     } catch (e) {
       // If any errors happen, just assume no notification box.
       this.log("Unable to get notify window: " + e.fileName + ":" + e.lineNumber + ": " + e.message);
       return null;
     }
   },
 
 
-  /*
-   * _getPopupNote
-   *
+  /**
    * Returns the popup notification to this prompter,
    * or null if there isn't one available.
    */
   _getPopupNote : function () {
     let popupNote = null;
 
     try {
       let { notifyWin } = this._getNotifyWindow();
@@ -1475,19 +1426,17 @@ LoginManagerPrompter.prototype = {
     } catch (e) {
       this.log("Popup notifications not available on window");
     }
 
     return popupNote;
   },
 
 
-  /*
-   * _getNotifyBox
-   *
+  /**
    * Returns the notification box to this prompter, or null if there isn't
    * a notification box available.
    */
   _getNotifyBox : function () {
     let notifyBox = null;
 
     try {
       let { notifyWin } = this._getNotifyWindow();
@@ -1500,34 +1449,30 @@ LoginManagerPrompter.prototype = {
     } catch (e) {
       this.log("Notification bars not available on window");
     }
 
     return notifyBox;
   },
 
 
-  /*
-   * _repickSelectedLogin
-   *
+  /**
    * The user might enter a login that isn't the one we prefilled, but
    * is the same as some other existing login. So, pick a login with a
    * matching username, or return null.
    */
   _repickSelectedLogin : function (foundLogins, username) {
     for (var i = 0; i < foundLogins.length; i++)
       if (foundLogins[i].username == username)
         return foundLogins[i];
     return null;
   },
 
 
-  /*
-   * _getLocalizedString
-   *
+  /**
    * Can be called as:
    *   _getLocalizedString("key1");
    *   _getLocalizedString("key2", ["arg1"]);
    *   _getLocalizedString("key3", ["arg1", "arg2"]);
    *   (etc)
    *
    * Returns the localized string for the specified key,
    * formatted if required.
@@ -1537,19 +1482,17 @@ LoginManagerPrompter.prototype = {
     if (formatArgs)
       return this._strBundle.formatStringFromName(
                                   key, formatArgs, formatArgs.length);
     else
       return this._strBundle.GetStringFromName(key);
   },
 
 
-  /*
-   * _sanitizeUsername
-   *
+  /**
    * Sanitizes the specified username, by stripping quotes and truncating if
    * it's too long. This helps prevent an evil site from messing with the
    * "save password?" prompt too much.
    */
   _sanitizeUsername : function (username) {
     if (username.length > 30) {
       username = username.substring(0, 30);
       username += this._ellipsis;
@@ -1571,19 +1514,17 @@ LoginManagerPrompter.prototype = {
     } else {
       uri = Services.io.newURI(aURI, null, null);
     }
 
     return uri.scheme + "://" + uri.hostPort;
   },
 
 
-  /*
-   * _getShortDisplayHost
-   *
+  /**
    * Converts a login's hostname field (a URL) to a short string for
    * prompting purposes. Eg, "http://foo.com" --> "foo.com", or
    * "ftp://www.site.co.uk" --> "site.co.uk".
    */
   _getShortDisplayHost: function (aURIString) {
     var displayHost;
 
     var eTLDService = Cc["@mozilla.org/network/effective-tld-service;1"].
@@ -1600,19 +1541,17 @@ LoginManagerPrompter.prototype = {
 
     if (!displayHost)
       displayHost = aURIString;
 
     return displayHost;
   },
 
 
-  /*
-   * _getAuthTarget
-   *
+  /**
    * Returns the hostname and realm for which authentication is being
    * requested, in the format expected to be used with nsILoginInfo.
    */
   _getAuthTarget : function (aChannel, aAuthInfo) {
     var hostname, realm;
 
     // If our proxy is demanding authentication, don't use the
     // channel's actual destination.