Ticket #43066: password-strength-meter.2.diff

src/wp-admin/js/password-strength-meter.js

@@ -3 +3 @@
 
 var passwordStrength;
 (function($){
+
+        /**
+         * The Password Strength object.
+         *
+         * Contains functions to determine the password strength.
+         *
+         * @since 3.7.0
+         *
+         * @namespace
+         */
         wp.passwordStrength = {
                 /**
-                 * Determine the strength of a given password
+                 * Determines the strength of a given password.
+                 *
+                 * @since 3.7.0
+                 *
+                 * @param {string} password1 The password.
+                 * @param {Array} blacklist An array of words that will lower the entropy of the password.
+                 * @param {string} password2 The confirmed password.
                  *
-                 * @param string password1 The password
-                 * @param array blacklist An array of words that will lower the entropy of the password
-                 * @param string password2 The confirmed password
+                 * @returns {number} The password strength score.
                  */
                 meter : function( password1, blacklist, password2 ) {
                         if ( ! $.isArray( blacklist ) )
@@ -28 +42 @@
                 },
 
                 /**
-                 * Builds an array of data that should be penalized, because it would lower the entropy of a password if it were used
+                 * Builds an array of data that should be penalized.
+                 *
+                 * Certain words need to be penalized because it would lower the entropy of a password if they were used.
+                 * The blacklist is based on user input fields such as username, first name, email etc.
+                 *
+                 * @since 3.7.0
                  *
-                 * @return array The array of data to be blacklisted
+                 * @returns {Array} The array of data to be blacklisted.
                  */
                 userInputBlacklist : function() {
                         var i, userInputFieldsLength, rawValuesLength, currentField,
@@ -38 +57 @@
                                 blacklist       = [],
                                 userInputFields = [ 'user_login', 'first_name', 'last_name', 'nickname', 'display_name', 'email', 'url', 'description', 'weblog_title', 'admin_email' ];
 
-                        // Collect all the strings we want to blacklist
+                        // Collect all the strings we want to blacklist.
                         rawValues.push( document.title );
                         rawValues.push( document.URL );
 
@@ -54 +73 @@
                                 rawValues.push( currentField.val() );
                         }
 
-                        // Strip out non-alphanumeric characters and convert each word to an individual entry
+                        // Strip out non-alphanumeric characters and convert each word to an individual entry.
                         rawValuesLength = rawValues.length;
                         for ( i = 0; i < rawValuesLength; i++ ) {
                                 if ( rawValues[ i ] ) {
@@ -62 +81 @@
                                 }
                         }
 
-                        // Remove empty values, short words, and duplicates. Short words are likely to cause many false positives.
+                        // Remove empty values, short words and duplicates. Short words are likely to cause many false positives.
                         blacklist = $.grep( blacklist, function( value, key ) {
                                 if ( '' === value || 4 > value.length ) {
                                         return false;
@@ -75 +94 @@
                 }
         };
 
-        // Back-compat.
+        // Backward compatibility.
         passwordStrength = wp.passwordStrength.meter;
 })(jQuery);