Docs: Improve documentation in wp-signup.php.

SergeyBiryukov · SergeyBiryukov · commit 976de7bdfb88 · 2021-08-31T12:23:46.000Z
* 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. git-svn-id: https://develop.svn.wordpress.org/trunk@51699 602fd350-edb4-49c9-b593-d223f7449a82
diff --git a/src/wp-signup.php b/src/wp-signup.php
@@ -15,7 +15,7 @@
 }
 
 /**
- * Prints signup_header via wp_head
+ * Prints signup_header via wp_head.
  *
  * @since MU (3.0.0)
  */
@@ -50,7 +50,7 @@ function do_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)
  */
@@ -89,7 +89,7 @@ function wpmu_signup_stylesheet() {
 <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.

Original file line number	Diff line number	Diff line change
`@@ -15,7 +15,7 @@`
`15`	`15`	`}`
`16`	`16`
`17`	`17`	`/**`
`18`		`- * Prints signup_header via wp_head`
	`18`	`+ * Prints signup_header via wp_head.`
`19`	`19`	`*`
`20`	`20`	`* @since MU (3.0.0)`
`21`	`21`	`*/`
`@@ -50,7 +50,7 @@ function do_signup_header() {`
`50`	`50`	`do_action( 'before_signup_header' );`
`51`	`51`
`52`	`52`	`/**`
`53`		`- * Prints styles for front-end Multisite signup pages`
	`53`	`+ * Prints styles for front-end Multisite signup pages.`
`54`	`54`	`*`
`55`	`55`	`* @since MU (3.0.0)`
`56`	`56`	`*/`
`@@ -89,7 +89,7 @@ function wpmu_signup_stylesheet() {`
`89`	`89`	`<div class="mu_register wp-signup-container" role="main">`
`90`	`90`	`<?php`
`91`	`91`	`/**`
`92`		`- * Generates and displays the Signup and Create Site forms`
	`92`	`+ * Generates and displays the Signup and Create Site forms.`
`93`	`93`	`*`
`94`	`94`	`* @since MU (3.0.0)`
`95`	`95`	`*`
`@@ -224,7 +224,7 @@ function show_blog_form( $blogname = '', $blog_title = '', $errors = '' ) {`
`224`	`224`	`}`
`225`	`225`
`226`	`226`	`/**`
`227`		`- * Validate the new site signup`
	`227`	`+ * Validates the new site signup.`
`228`	`228`	`*`
`229`	`229`	`* @since MU (3.0.0)`
`230`	`230`	`*`
`@@ -288,7 +288,7 @@ function show_user_form( $user_name = '', $user_email = '', $errors = '' ) {`
`288`	`288`	`}`
`289`	`289`
`290`	`290`	`/**`
`291`		`- * Validate user signup name and email`
	`291`	`+ * Validates user signup name and email.`
`292`	`292`	`*`
`293`	`293`	`* @since MU (3.0.0)`
`294`	`294`	`*`
`@@ -300,7 +300,7 @@ function validate_user_form() {`
`300`	`300`	`}`
`301`	`301`
`302`	`302`	`/**`
`303`		`- * Allow returning users to sign up for another site`
	`303`	`+ * Shows a form for returning users to sign up for another site.`
`304`	`304`	`*`
`305`	`305`	`* @since MU (3.0.0)`
`306`	`306`	`*`
`@@ -394,17 +394,17 @@ function signup_another_blog( $blogname = '', $blog_title = '', $errors = '' ) {`
`394`	`394`	`}`
`395`	`395`
`396`	`396`	`/**`
`397`		`- * Validate a new site signup for an existing user.`
`398`		`- *`
`399`		`- * @global string $blogname The new site's subdomain or directory name.`
`400`		`- * @global string $blog_title The new site's title.`
`401`		`- * @global WP_Error $errors Existing errors in the global scope.`
`402`		`- * @global string $domain The new site's domain.`
`403`		`- * @global string $path The new site's path.`
	`397`	`+ * Validates a new site signup for an existing user.`
`404`	`398`	`*`
`405`	`399`	`* @since MU (3.0.0)`
`406`	`400`	`*`
`407`		`- * @return null\|bool True if site signup was validated, false if error.`
	`401`	`+ * @global string $blogname The new site's subdomain or directory name.`
	`402`	`+ * @global string $blog_title The new site's title.`
	`403`	`+ * @global WP_Error $errors Existing errors in the global scope.`
	`404`	`+ * @global string $domain The new site's domain.`
	`405`	`+ * @global string $path The new site's path.`
	`406`	`+ *`
	`407`	`+ * @return null\|bool True if site signup was validated, false on error.`
`408`	`408`	`* The function halts all execution if the user is not logged in.`
`409`	`409`	`*/`
`410`	`410`	`function validate_another_blog_signup() {`
`@@ -486,7 +486,7 @@ function validate_another_blog_signup() {`
`486`	`486`	`}`
`487`	`487`
`488`	`488`	`/**`
`489`		`- * Confirm a new site signup.`
	`489`	`+ * Shows a message confirming that the new site has been created.`
`490`	`490`	`*`
`491`	`491`	`* @since MU (3.0.0)`
`492`	`492`	* @since 4.4.0 Added the `$blog_id` parameter.
`@@ -553,6 +553,9 @@ function confirm_another_blog_signup( $domain, $path, $blog_title, $user_name, $`
`553`	`553`	`*`
`554`	`554`	`* @since MU (3.0.0)`
`555`	`555`	`*`
	`556`	`+ * @global string $active_signup String that returns registration type. The value can be`
	`557`	`+ * 'all', 'none', 'blog', or 'user'.`
	`558`	`+ *`
`556`	`559`	`* @param string $user_name The username.`
`557`	`560`	`* @param string $user_email The user's email.`
`558`	`561`	`* @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 = '' ) {`
`626`	`629`	`}`
`627`	`630`
`628`	`631`	`/**`
`629`		`- * Validate the new user signup`
	`632`	`+ * Validates the new user signup.`
`630`	`633`	`*`
`631`	`634`	`* @since MU (3.0.0)`
`632`	`635`	`*`
`633`		`- * @return bool True if new user signup was validated, false if error`
	`636`	`+ * @return bool True if new user signup was validated, false on error.`
`634`	`637`	`*/`
`635`	`638`	`function validate_user_signup() {`
`636`	`639`	`$result = validate_user_form();`
`@@ -656,12 +659,12 @@ function validate_user_signup() {`
`656`	`659`	`}`
`657`	`660`
`658`	`661`	`/**`
`659`		`- * New user signup confirmation`
	`662`	`+ * Shows a message confirming that the new user has been registered and is awaiting activation.`
`660`	`663`	`*`
`661`	`664`	`* @since MU (3.0.0)`
`662`	`665`	`*`
`663`		`- * @param string $user_name The username`
`664`		`- * @param string $user_email The user's email address`
	`666`	`+ * @param string $user_name The username.`
	`667`	`+ * @param string $user_email The user's email address.`
`665`	`668`	`*/`
`666`	`669`	`function confirm_user_signup( $user_name, $user_email ) {`
`667`	`670`	`?>`
`@@ -750,11 +753,11 @@ function signup_blog( $user_name = '', $user_email = '', $blogname = '', $blog_t`
`750`	`753`	`}`
`751`	`754`
`752`	`755`	`/**`
`753`		`- * Validate new site signup`
	`756`	`+ * Validates new site signup.`
`754`	`757`	`*`
`755`	`758`	`* @since MU (3.0.0)`
`756`	`759`	`*`
`757`		`- * @return bool True if the site signup was validated, false if error`
	`760`	`+ * @return bool True if the site signup was validated, false on error.`
`758`	`761`	`*/`
`759`	`762`	`function validate_blog_signup() {`
`760`	`763`	`// Re-validate user info.`