PHPDoc updates for /wp-includes/user.php

[morganestes]

Added PHPDoc blocks for two functions introduced in 2.8, and updated signatures in others for better specificity of params and returns.

[morganestes]

Refreshed patch with updates after other docs added.

[morganestes]

Refreshed patch. One thing different is in wp_signon(), where $credentials was set as an optional string, but is actually an array in the function, so I made the signature change to reflect what was actually being used/checked for. I didn't think I was stretching too far in doing so as part of an inline doc update, but if that's not the case I can change back to the previous signature.

[azizur]

This patch also addresses #27130

[DrewAPicture]

#27130 was marked as a duplicate.

[SergeyBiryukov]

26148.2.patch​ is another pass.

• $secure_cookie should remain bool, even if its default value is a string, see 2:ticket:27130.
• add_filter() in line 105 is redundant since [24848].
• Removed some obsolete $wpdb references.
• Some more fixes and additions.

[SergeyBiryukov]

Replying to SergeyBiryukov:

add_filter() in line 105 is redundant since [24848].

It should probably be removed in a separate commit to avoid confusion.

[DrewAPicture]

As is the custom in inline-documentation patches, there should not be any code changes that fall outside of basic documentation needs. Basic needs could include things like adding braces to conditionals after adding inline documentation. Those needs would, however, exclude things like unnecessary whitespacing.

So, as in 26148.2.patch​:

• The parameter default change in wp_signon() should be removed.
• Whitespacing in wp_authenticate_username_password(), and wp_authenticate_cookie() should be removed.

[SergeyBiryukov]

Replying to DrewAPicture:

The parameter default change in wp_signon() should be removed.

Let's reopen #27130 then :)

[DrewAPicture]

Replying to SergeyBiryukov:

Replying to DrewAPicture:

The parameter default change in wp_signon() should be removed.

Let's reopen #27130 then :)

Re-opened.

[SergeyBiryukov]

Replying to SergeyBiryukov:

add_filter() in line 105 is redundant since [24848].

Moved to #27255.

[SergeyBiryukov]

Replying to DrewAPicture:

As is the custom in inline-documentation patches, there should not be any code changes that fall outside of basic documentation needs.

26148.3.patch​ excludes unrelated changes.

[DrewAPicture]

In 27353:

Inline documentation improvements for wp-includes/user.php.

Props morganestes, SergeyBiryukov.
Fixes #26148.

[SergeyBiryukov]

Just noted that $username and $password in wp_authenticate_cookie() are always passed.

26148.4.patch​ is an additional clarification.

[SergeyBiryukov]

In 27354:

Additional clarification for wp_authenticate_cookie() parameters.

fixes #26148.