From d268976255c94d6fe75618e43e6249b327d35272 Mon Sep 17 00:00:00 2001
From: atimmer <atimmer@git.wordpress.org>
Date: Thu, 18 Jan 2018 13:39:33 +0000
Subject: [PATCH] Docs: Improve JSDoc for `password-strength-meter.js`.

Props herregroen, carolinegeven, ireneyoast, jjcomack.
Fixes #43066.

Built from https://develop.svn.wordpress.org/trunk@42528


git-svn-id: http://core.svn.wordpress.org/trunk@42357 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-admin/js/password-strength-meter.js | 58 +++++++++++++++++++++-----
 wp-includes/version.php                |  2 +-
 2 files changed, 49 insertions(+), 11 deletions(-)

diff --git a/wp-admin/js/password-strength-meter.js b/wp-admin/js/password-strength-meter.js
index efd26bbc5a..8b903b497a 100644
--- a/wp-admin/js/password-strength-meter.js
+++ b/wp-admin/js/password-strength-meter.js
@@ -3,13 +3,28 @@ window.wp = window.wp || {};
 
 var passwordStrength;
 (function($){
+
+	/**
+	 * 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.
 		 *
-		 * @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
+		 * Compares first password to the password confirmation.
+		 *
+		 * @since 3.7.0
+		 *
+		 * @param {string} password1 The subject password.
+		 * @param {Array}  blacklist An array of words that will lower the entropy of
+		 *                           the password.
+		 * @param {string} password2 The password confirmation.
+		 *
+		 * @returns {number} The password strength score.
 		 */
 		meter : function( password1, blacklist, password2 ) {
 			if ( ! $.isArray( blacklist ) )
@@ -28,9 +43,15 @@ var passwordStrength;
 		},
 
 		/**
-		 * 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 words that should be penalized.
 		 *
-		 * @return array The array of data to be blacklisted
+		 * 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
+		 *
+		 * @returns {string[]} The array of words to be blacklisted.
 		 */
 		userInputBlacklist : function() {
 			var i, userInputFieldsLength, rawValuesLength, currentField,
@@ -38,7 +59,7 @@ var passwordStrength;
 				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,7 +75,10 @@ var passwordStrength;
 				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,7 +86,10 @@ var passwordStrength;
 				}
 			}
 
-			// 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,6 +102,17 @@ var passwordStrength;
 		}
 	};
 
-	// Back-compat.
+	// Backward compatibility.
+
+	/**
+	 * Password strength meter function.
+	 *
+	 * @since 2.5.0
+	 * @deprecated 3.7.0 Use wp.passwordStrength.meter instead.
+	 *
+	 * @global
+	 *
+	 * @type {wp.passwordStrength.meter}
+	 */
 	passwordStrength = wp.passwordStrength.meter;
 })(jQuery);
diff --git a/wp-includes/version.php b/wp-includes/version.php
index d5a66537a0..44be45792a 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.0-alpha-42527';
+$wp_version = '5.0-alpha-42528';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.