From c73609fe10534abfabe0b79199152aa00045b375 Mon Sep 17 00:00:00 2001
From: Sergey Biryukov <sergeybiryukov.ru@gmail.com>
Date: Tue, 31 Aug 2021 12:25:00 +0000
Subject: [PATCH] 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
---
 wp-includes/version.php |  2 +-
 wp-signup.php           | 47 ++++++++++++++++++++++-------------------
 2 files changed, 26 insertions(+), 23 deletions(-)

diff --git a/wp-includes/version.php b/wp-includes/version.php
index 29baa33977..819534e9cf 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -13,7 +13,7 @@
  *
  * @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.
diff --git a/wp-signup.php b/wp-signup.php
index cbc4ddb402..e13d6e49e7 100644
--- a/wp-signup.php
+++ b/wp-signup.php
@@ -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)
  */
@@ -50,7 +50,7 @@ $wp_query->is_404 = false;
 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)
  */
@@ -89,7 +89,7 @@ do_action( 'before_signup_form' );
 <div class="mu_register wp-signup-container" role="main">
 <?php
 /**
- * Generates and displays the Signup and Create Site forms
+ * Generates and displays the Signup and Create Site forms.
  *
  * @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)
  *
@@ -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)
  *
@@ -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)
  *
@@ -394,17 +394,17 @@ function signup_another_blog( $blogname = '', $blog_title = '', $errors = '' ) {
 }
 
 /**
- * Validate a new site signup for an existing user.
- *
- * @global string          $blogname   The new site's subdomain or directory name.
- * @global string          $blog_title The new site's title.
- * @global WP_Error        $errors     Existing errors in the global scope.
- * @global string          $domain     The new site's domain.
- * @global string          $path       The new site's path.
+ * Validates a new site signup for an existing user.
  *
  * @since MU (3.0.0)
  *
- * @return null|bool True if site signup was validated, false if error.
+ * @global string   $blogname   The new site's subdomain or directory name.
+ * @global string   $blog_title The new site's title.
+ * @global WP_Error $errors     Existing errors in the global scope.
+ * @global string   $domain     The new site's domain.
+ * @global string   $path       The new site's path.
+ *
+ * @return null|bool True if site signup was validated, false on error.
  *                   The function halts all execution if the user is not logged in.
  */
 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 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)
  *
+ * @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_email The user's email.
  * @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)
  *
- * @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() {
 	$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)
  *
- * @param string $user_name The username
- * @param string $user_email The user's email address
+ * @param string $user_name  The username.
+ * @param string $user_email The user's email address.
  */
 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)
  *
- * @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() {
 	// Re-validate user info.