Docs: Various docblock improvements related to user and site signup functionality.

See #50768

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


git-svn-id: http://core.svn.wordpress.org/trunk@48840 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/ms-delete-site.php

@@ -72,11 +72,11 @@ All at ###SITENAME###
 ###SITEURL###"
 	);
 	/**
-	 * Filters the email content sent when a site in a Multisite network is deleted.
+	 * Filters the text for the email sent to the site admin when a request to delete a site in a Multisite network is submitted.
 	 *
 	 * @since 3.0.0
 	 *
-	 * @param string $content The email content that will be sent to the user who deleted a site in a Multisite network.
+	 * @param string $content The email text.
 	 */
 	$content = apply_filters( 'delete_site_email_content', $content );
 

wp-includes/ms-functions.php

@@ -1575,7 +1575,7 @@ function domain_exists( $domain, $path, $network_id = 1 ) {
 }
 
 /**
- * Notify a user that their blog activation has been successful.
+ * Notifies the site administrator that their site activation was successful.
  *
  * Filter {@see 'wpmu_welcome_notification'} to disable or bypass.
  *
@@ -1584,26 +1584,26 @@ function domain_exists( $domain, $path, $network_id = 1 ) {
  *
  * @since MU (3.0.0)
  *
- * @param int    $blog_id  Blog ID.
+ * @param int    $blog_id  Site ID.
  * @param int    $user_id  User ID.
- * @param string $password User password.
+ * @param string $password User password, or "N/A" if the user account is not new.
  * @param string $title    Site title.
  * @param array  $meta     Optional. Signup meta data. By default, contains the requested privacy setting and lang_id.
- * @return bool
+ * @return bool Whether the email notification was sent.
  */
 function wpmu_welcome_notification( $blog_id, $user_id, $password, $title, $meta = array() ) {
 	$current_network = get_network();
 
 	/**
-	 * Filters whether to bypass the welcome email after site activation.
+	 * Filters whether to bypass the welcome email sent to the site administrator after site activation.
 	 *
 	 * Returning false disables the welcome email.
 	 *
 	 * @since MU (3.0.0)
 	 *
-	 * @param int|bool $blog_id  Blog ID.
-	 * @param int      $user_id  User ID.
-	 * @param string   $password User password.
+	 * @param int|bool $blog_id  Site ID.
+	 * @param int      $user_id  User ID of the site administrator.
+	 * @param string   $password User password, or "N/A" if the user account is not new.
 	 * @param string   $title    Site title.
 	 * @param array    $meta     Signup meta data. By default, contains the requested privacy setting and lang_id.
 	 */
@@ -1645,16 +1645,16 @@ We hope you enjoy your new site. Thanks!
 	$welcome_email = str_replace( 'PASSWORD', $password, $welcome_email );
 
 	/**
-	 * Filters the content of the welcome email after site activation.
+	 * Filters the content of the welcome email sent to the site administrator after site activation.
 	 *
 	 * Content should be formatted for transmission via wp_mail().
 	 *
 	 * @since MU (3.0.0)
 	 *
 	 * @param string $welcome_email Message body of the email.
-	 * @param int    $blog_id       Blog ID.
-	 * @param int    $user_id       User ID.
-	 * @param string $password      User password.
+	 * @param int    $blog_id       Site ID.
+	 * @param int    $user_id       User ID of the site administrator.
+	 * @param string $password      User password, or "N/A" if the user account is not new.
 	 * @param string $title         Site title.
 	 * @param array  $meta          Signup meta data. By default, contains the requested privacy setting and lang_id.
 	 */
@@ -1678,7 +1678,7 @@ We hope you enjoy your new site. Thanks!
 	$subject = __( 'New %1$s Site: %2$s' );
 
 	/**
-	 * Filters the subject of the welcome email after site activation.
+	 * Filters the subject of the welcome email sent to the site administrator after site activation.
 	 *
 	 * @since MU (3.0.0)
 	 *

wp-includes/version.php

@@ -13,7 +13,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.6-alpha-49077';
+$wp_version = '5.6-alpha-49078';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.

wp-login.php

@@ -323,7 +323,7 @@ function login_footer( $input_id = '' ) {
 }
 
 /**
- * Outputs the Javascript to handle the form shaking.
+ * Outputs the Javascript to handle the form shaking on the login page.
  *
  * @since 3.0.0
  */
@@ -336,7 +336,7 @@ function wp_shake_js() {
 }
 
 /**
- * Outputs the viewport meta tag.
+ * Outputs the viewport meta tag for the login page.
  *
  * @since 3.7.0
  */
@@ -347,11 +347,11 @@ function wp_login_viewport_meta() {
 }
 
 /**
- * Handles sending password retrieval email to user.
+ * Handles sending a password retrieval email to a user.
  *
  * @since 2.5.0
  *
- * @return bool|WP_Error True: when finish. WP_Error on error
+ * @return true|WP_Error True when finished, WP_Error object on error.
  */
 function retrieve_password() {
 	$errors    = new WP_Error();
@@ -422,7 +422,7 @@ function retrieve_password() {
 	} else {
 		/*
 		 * The blogname option is escaped with esc_html on the way into the database
-		 * in sanitize_option we want to reverse this for the plain text arena of emails.
+		 * in sanitize_option. We want to reverse this for the plain text arena of emails.
 		 */
 		$site_name = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES );
 	}
@@ -445,7 +445,7 @@ function retrieve_password() {
 	 * @since 2.8.0
 	 * @since 4.4.0 Added the `$user_login` and `$user_data` parameters.
 	 *
-	 * @param string  $title      Default email title.
+	 * @param string  $title      Email subject.
 	 * @param string  $user_login The username for the user.
 	 * @param WP_User $user_data  WP_User object.
 	 */
@@ -459,7 +459,7 @@ function retrieve_password() {
 	 * @since 2.8.0
 	 * @since 4.1.0 Added `$user_login` and `$user_data` parameters.
 	 *
-	 * @param string  $message    Default mail message.
+	 * @param string  $message    Email message.
 	 * @param string  $key        The activation key.
 	 * @param string  $user_login The username for the user.
 	 * @param WP_User $user_data  WP_User object.

wp-signup.php

@@ -240,7 +240,7 @@ function validate_blog_form() {
 }
 
 /**
- * Display user registration form
+ * Displays the fields for the new user account registration form.
  *
  * @since MU (3.0.0)
  *
@@ -277,7 +277,7 @@ function show_user_form( $user_name = '', $user_email = '', $errors = '' ) {
 		echo '<p class="error">' . $errmsg . '</p>';
 	}
 	/**
-	 * Fires at the end of the user registration form on the site sign-up form.
+	 * Fires at the end of the new user account registration form.
 	 *
 	 * @since 3.0.0
 	 *
@@ -547,7 +547,7 @@ function confirm_another_blog_signup( $domain, $path, $blog_title, $user_name, $
 }
 
 /**
- * Setup the new user signup process
+ * Shows a form for a visitor to sign up for a new user account.
  *
  * @since MU (3.0.0)
  *
@@ -683,7 +683,7 @@ function confirm_user_signup( $user_name, $user_email ) {
 }
 
 /**
- * Setup the new site signup
+ * Shows a form for a user or visitor to sign up for a new site.
  *
  * @since MU (3.0.0)
  *
@@ -807,13 +807,13 @@ function validate_blog_signup() {
 }
 
 /**
- * New site signup confirmation
+ * Shows a message confirming that the new site has been registered and is awaiting activation.
  *
  * @since MU (3.0.0)
  *
- * @param string $domain     The domain URL.
- * @param string $path       The site root path.
- * @param string $blog_title The new site title.
+ * @param string $domain     The domain or subdomain of the site.
+ * @param string $path       The path of the site.
+ * @param string $blog_title The title of the new site.
  * @param string $user_name  The user's username.
  * @param string $user_email The user's email address.
  * @param array  $meta       Any additional meta from the {@see 'add_signup_meta'} filter in validate_blog_signup().