PHPDoc updates for /wp-includes/functions.php

[morganestes]

Style fixes to add periods, arrange keywords in the correct order, and correct @param and @return values (adding descriptions when needed).

[jeremyfelt]

Looks good, @morganestes.

A couple notes from a read through:

• docs for _http_build_query() seem to have some spacing issues around the params
• similar spacing issues in docs for wp_filter_object_list()

[morganestes]

Refresh

[morganestes]

Replying to jeremyfelt:

• docs for _http_build_query() seem to have some spacing issues around the params
• similar spacing issues in docs for wp_filter_object_list()

Thanks for checking it out. I adjusted the spacing on those two doc blocks and added it as a .1 diff.

[DrewAPicture]

Ideally, I'd like to avoid these huge patches in the future, instead focusing on specific change. It's tough to follow what's being changed and why, etc.

That said, here are some notes on 26185.1.diff​:

Reference: ​Inline Documentation Standards

• There should always be a new blank line between the short and long descriptions in a doc block
• If you're going to add parameter descriptions, great. I'd prefer it if you consistently space-aligned the parts for parameters. Case in point, compare your docs changes for date_i18n() vs deprecated_file(). The style used with date_i18n() is definitely preferred :)
• Please avoid adding new @global tags
• @link, @see, etc. tags should always fall below the @since
• If parameter description is wrapped, align with the first character of the first line with spaces
• For hash notations (arrays), use a 4-space indent for each level of the array, not tabs

[morganestes]

Replying to DrewAPicture:

Ideally, I'd like to avoid these huge patches in the future, instead focusing on specific change. It's tough to follow what's being changed and why, etc.

Is it better to have a separate patch for each function/hook that I'm documenting?

I'll look at the overall structure again. I relied too much on my IDE autogenerating and formatting and it bit me. I'll go back and try again.

[morganestes]

I'm going back through this after 3.9 and will try again. This time, I'm adding a diff per function with major changes, and a combined one for just whitespace changes.

[morganestes]

date_i18n

[morganestes]

Added complete documentation of _http_build_query()

[DrewAPicture]

Replying to morganestes:

I'm going back through this after 3.9 and will try again. This time, I'm adding a diff per function with major changes, and a combined one for just whitespace changes.

Great. Honestly, I'd prefer you group up PHPDoc changes for multiple functions in patches. You don't need to do the whole file in one patch, but I'd rather not have 40 tiny patches either.

Also, you can skip the whitespace changes. The only time whitespace changes are really accepted is when they're on lines already affect by code-level changes. This is to prevent unnecessary churn in the codebase.

[morganestes]

Added parameter and return tags to wp_auth_check().

[morganestes]

Added parameter and return tags to wp_checkdate.

[morganestes]

Replying to DrewAPicture:

Great. Honestly, I'd prefer you group up PHPDoc changes for multiple functions in patches. You don't need to do the whole file in one patch, but I'd rather not have 40 tiny patches either.

Sorry, didn't see this until I started adding the individual patches. I'll merge then into one more patch, and that should be it for this ticket.

[morganestes]

Consolidated patch with 4 functions documented.

[wonderboymusic]

This might be 4.0 material

[DrewAPicture]

In 28917:

Improve inline documentation for date_i18n(), _http_build_query(), wp_checkdate(), and wp_auth_check().

Props morganestes.
See #26185.

[DrewAPicture]

In 28918:

General inline documentation improvements in wp-includes/functions.php.

First run. See #26185.

[DrewAPicture]

In 28936:

General inline documentation improvements in wp-includes/functions.php.

Second run. See #26185.

[SergeyBiryukov]

In 28937:

Some fixes for get_weekstartend() docs.

see #26185.

[DrewAPicture]

In 29011:

General inline documentation improvements in wp-includes/functions.php.

Final run. Fixes #26185.

[TobiasBg]

Found two inconsistencies in [29011], in the grammar for the _deprecated_*() functions, plus coding standards in the example PHP code, see 26185.2.diff.

[DrewAPicture]

In 29013:

Fix inconsistent language in two function descriptions in wp-includes/functions.php.

Also adds correct coding standards to a code sample in _deprecated_argument().

Props TobiasBg.
Fixes #26185.