From 1079647d30f6cc5eab56c992e0a5f508426439b0 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Wed, 30 Sep 2020 21:54:07 +0000 Subject: [PATCH] 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 | 4 ++-- wp-includes/ms-functions.php | 26 +++++++++++++------------- wp-includes/version.php | 2 +- wp-login.php | 14 +++++++------- wp-signup.php | 16 ++++++++-------- 5 files changed, 31 insertions(+), 31 deletions(-) diff --git a/wp-admin/ms-delete-site.php b/wp-admin/ms-delete-site.php index 28c05ded60..c552f354f3 100644 --- a/wp-admin/ms-delete-site.php +++ b/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 ); diff --git a/wp-includes/ms-functions.php b/wp-includes/ms-functions.php index 8f673ce5bc..0f8fafaa13 100644 --- a/wp-includes/ms-functions.php +++ b/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) * diff --git a/wp-includes/version.php b/wp-includes/version.php index 782c555a5c..3518babb6c 100644 --- a/wp-includes/version.php +++ b/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. diff --git a/wp-login.php b/wp-login.php index 320ea909b5..0135ecffb7 100644 --- a/wp-login.php +++ b/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. diff --git a/wp-signup.php b/wp-signup.php index bd279e12c1..8dacd322b1 100644 --- a/wp-signup.php +++ b/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 '

' . $errmsg . '

'; } /** - * 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().