Docs: Improve documentation in `wp-signup.php`.

* Document the `$active_signup` global in `signup_user()`.
* Update some DocBlocks per the documentation standards.
* Expand some function descriptions for clarity.

Follow-up to [37535], [37536], [41200], [43326], [49078], [50828].

Props mt8.biz, sabernhardt, audrasjb, westonruter, jayupadhyay01, mukesh27, SergeyBiryukov.
Fixes #41566.
Built from https://develop.svn.wordpress.org/trunk@51699


git-svn-id: http://core.svn.wordpress.org/trunk@51305 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Sergey Biryukov 2021-08-31 12:25:00 +00:00
parent 4abb89f6c6
commit c73609fe10
2 changed files with 26 additions and 23 deletions

View File

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

View File

@ -15,7 +15,7 @@ if ( is_array( get_site_option( 'illegal_names' ) ) && isset( $_GET['new'] ) &&
} }
/** /**
* Prints signup_header via wp_head * Prints signup_header via wp_head.
* *
* @since MU (3.0.0) * @since MU (3.0.0)
*/ */
@ -50,7 +50,7 @@ $wp_query->is_404 = false;
do_action( 'before_signup_header' ); do_action( 'before_signup_header' );
/** /**
* Prints styles for front-end Multisite signup pages * Prints styles for front-end Multisite signup pages.
* *
* @since MU (3.0.0) * @since MU (3.0.0)
*/ */
@ -89,7 +89,7 @@ do_action( 'before_signup_form' );
<div class="mu_register wp-signup-container" role="main"> <div class="mu_register wp-signup-container" role="main">
<?php <?php
/** /**
* Generates and displays the Signup and Create Site forms * Generates and displays the Signup and Create Site forms.
* *
* @since MU (3.0.0) * @since MU (3.0.0)
* *
@ -224,7 +224,7 @@ function show_blog_form( $blogname = '', $blog_title = '', $errors = '' ) {
} }
/** /**
* Validate the new site signup * Validates the new site signup.
* *
* @since MU (3.0.0) * @since MU (3.0.0)
* *
@ -288,7 +288,7 @@ function show_user_form( $user_name = '', $user_email = '', $errors = '' ) {
} }
/** /**
* Validate user signup name and email * Validates user signup name and email.
* *
* @since MU (3.0.0) * @since MU (3.0.0)
* *
@ -300,7 +300,7 @@ function validate_user_form() {
} }
/** /**
* Allow returning users to sign up for another site * Shows a form for returning users to sign up for another site.
* *
* @since MU (3.0.0) * @since MU (3.0.0)
* *
@ -394,7 +394,9 @@ function signup_another_blog( $blogname = '', $blog_title = '', $errors = '' ) {
} }
/** /**
* Validate a new site signup for an existing user. * Validates a new site signup for an existing user.
*
* @since MU (3.0.0)
* *
* @global string $blogname The new site's subdomain or directory name. * @global string $blogname The new site's subdomain or directory name.
* @global string $blog_title The new site's title. * @global string $blog_title The new site's title.
@ -402,9 +404,7 @@ function signup_another_blog( $blogname = '', $blog_title = '', $errors = '' ) {
* @global string $domain The new site's domain. * @global string $domain The new site's domain.
* @global string $path The new site's path. * @global string $path The new site's path.
* *
* @since MU (3.0.0) * @return null|bool True if site signup was validated, false on error.
*
* @return null|bool True if site signup was validated, false if error.
* The function halts all execution if the user is not logged in. * The function halts all execution if the user is not logged in.
*/ */
function validate_another_blog_signup() { function validate_another_blog_signup() {
@ -486,7 +486,7 @@ function validate_another_blog_signup() {
} }
/** /**
* Confirm a new site signup. * Shows a message confirming that the new site has been created.
* *
* @since MU (3.0.0) * @since MU (3.0.0)
* @since 4.4.0 Added the `$blog_id` parameter. * @since 4.4.0 Added the `$blog_id` parameter.
@ -553,6 +553,9 @@ function confirm_another_blog_signup( $domain, $path, $blog_title, $user_name, $
* *
* @since MU (3.0.0) * @since MU (3.0.0)
* *
* @global string $active_signup String that returns registration type. The value can be
* 'all', 'none', 'blog', or 'user'.
*
* @param string $user_name The username. * @param string $user_name The username.
* @param string $user_email The user's email. * @param string $user_email The user's email.
* @param WP_Error|string $errors A WP_Error object containing existing errors. Defaults to empty string. * @param WP_Error|string $errors A WP_Error object containing existing errors. Defaults to empty string.
@ -626,11 +629,11 @@ function signup_user( $user_name = '', $user_email = '', $errors = '' ) {
} }
/** /**
* Validate the new user signup * Validates the new user signup.
* *
* @since MU (3.0.0) * @since MU (3.0.0)
* *
* @return bool True if new user signup was validated, false if error * @return bool True if new user signup was validated, false on error.
*/ */
function validate_user_signup() { function validate_user_signup() {
$result = validate_user_form(); $result = validate_user_form();
@ -656,12 +659,12 @@ function validate_user_signup() {
} }
/** /**
* New user signup confirmation * Shows a message confirming that the new user has been registered and is awaiting activation.
* *
* @since MU (3.0.0) * @since MU (3.0.0)
* *
* @param string $user_name The username * @param string $user_name The username.
* @param string $user_email The user's email address * @param string $user_email The user's email address.
*/ */
function confirm_user_signup( $user_name, $user_email ) { function confirm_user_signup( $user_name, $user_email ) {
?> ?>
@ -750,11 +753,11 @@ function signup_blog( $user_name = '', $user_email = '', $blogname = '', $blog_t
} }
/** /**
* Validate new site signup * Validates new site signup.
* *
* @since MU (3.0.0) * @since MU (3.0.0)
* *
* @return bool True if the site signup was validated, false if error * @return bool True if the site signup was validated, false on error.
*/ */
function validate_blog_signup() { function validate_blog_signup() {
// Re-validate user info. // Re-validate user info.