Add docblocks to wp-signup.php

[DrewAPicture]

It's my understanding that wp-signup.php has sort of fallen by the wayside in the recent past and could use some love. By no stretch of my imagination do I think I know all there is to know about what needs to happen here, but doesn't hurt to get the ball rolling.

Some action items I can already suggest would be:

• Make it possible to overload the hard-coded CSS
• Add some docblocks for the many functions in the file
• Cleanup coding standards and optimize strings
• ???

Howdy from #WCDEN Hack Day, I thought I'd try to work on the lower-level bits today.

A ​conversation in IRC with @dd32 this morning led to 22187-signup-styles.diff​ which I think should easily allow themes to overload the hard-coded styles. I'm still not totally clear on the reasoning behind adding or not adding actions/filters to default-filters.php.

Related: #17166 - wp-signup dynamic strings to static strings

Docblocks for all functions + changes from 22187-signup-styles.diff

22187.2.diff + general cleanup of the entire file

Attached 22187.3.diff​ which:

• Allows for overloading the hard-coded CSS
• Adds first-pass docblocks to all the functions
• General coding standards and code clarification through the whole file

TODO: Clarify docblocks, look at moving some of the functions out to ms-functions.php

Add some missing semicolons causing WSOD

Some more related tickets:

• #17630 - Redirect wp-signup.php to wp_signup_location
• #19451 - Cannot distinguish which WordPress Signup stage I am
• #17948 - Enhancements to the login and registration forms
• #16833 - Signup mechanism shortens usernames without warning
• #20107 - Add Filter for user_name length in ms user signup

Just the docblocks

The OCD in previous aside, 22187-docblocks.diff​ just adds docblocks to wp-signup.

Some text needs updating:

The default styles are printed via signup_header which is hooked to wp_head.  
They can be overloaded by replacing the output on the signup_header action hook. 

This was the case in 22187.4.diff​, but not in 22187-docblocks.diff​.

Replying to SergeyBiryukov:

Good catch Sergey. 22187-docblocks.2.diff should cover it. See anything else that stands out?

In 23362:

Add inline documentation for wp-signup.php. props DrewAPicture. fixes #22187.

As noted in ticket:24210:11, $meta value passed to confirm_blog_signup() and confirm_another_blog_signup() is an array, not a string (although it's unused in both functions):
tags/3.5.1/wp-signup.php#L209​, tags/3.5.1/wp-signup.php#L343​.

Also, there's an inconsistency in optional arguments. In confirm_blog_signup(), both $user_name and $user_email are optional. In confirm_another_blog_signup(), $user_name is required. Neither of them make sense as optional there, but that's out of scope for this ticket.

In 24262:

Correct default value and inline description for $meta argument. see #22187.

See [23362] and [24262] for phpdoc updates to:

• do_signup_header()
• wpmu_signup_stylesheet()
• show_blog_form()
• validate_blog_form()
• show_user_form()
• validate_user_form()
• signup_another_blog()
• validate_another_blog_signup()
• confirm_another_blog_signup()
• signup_user()
• validate_user_signup()
• confirm_user_signup()
• signup_blog()
• validate_blog_signup()
• confirm_blog_signup()

Looks good, thanks. I am not so sure about the @since MU – shouldn’t that be a real version number (3.0)?

@since MU is not the same as @since 3.0.0, it's used for functions that actually come from the MU codebase. The difference is specifically mentioned in ticket:16702:1.