Docblock improvements for 4.9

[DrewAPicture]

Previously:

• #39130 (4.8)
• #37770 (4.7)
• #32246 (4.6)

[DrewAPicture]

In 40898:

Docs: Correct a typo in the sort_column argument description for wp_page_menu().

h/t spacegrrl.
See #41017.

[DrewAPicture]

In 40899:

Docs: Clarify that get_the_author_meta() can also return an empty string.

h/t aurovrata.
See #41017

[DrewAPicture]

In 40900:

Docs: Include 'parent' as an acceptable entry for the $orderby argument in WP_Term_Query.

h/t kalor.
See #41017.

[jnylen0]

Does h/t username include someone in the props list for a release?

cc @ocean90 @jorbin @SergeyBiryukov - let's get the scripts that generate props lists posted somewhere.

[DrewAPicture]

In 40930:

Docs: Add more complete documentation about expected values in the $meta parameter for wpmu_create_blog().

See #41017.

[DrewAPicture]

In 40931:

Docs: Fix a typo in the description for the get_previous_post_link() $link parameter. The default value is '%title', not '%title%'.

Props kmgalanakis.
See #41017.

[DrewAPicture]

In 40932:

Docs: Clarify the description for esc_html__() to note that the original text will be escaped on return if there is no translation, or the text domain isn't loaded.

Props brianlayman.
See #41017.

[DrewAPicture]

In 40933:

Docs: Improve description wording for get_template_part() in regard to overloading by child themes.

Also, update the summary to use a third-person singular verb.

Props ixmati.
See #41017.

[DrewAPicture]

In 40937:

Docs: Fix alignment of the $output parameter in the hook doc for the do_shortcode_tag filter.

See #41017.

[DrewAPicture]

In 40970:

Docs: Use third-person singular verbs in the summaries for wp_unschedule_hook() and wp_clear_scheduled_hook().

See #41017.

[DrewAPicture]

In 40985:

Docs: Add a valid return type for post_preview() and improve the DocBlock summary.

See #41017.

[DrewAPicture]

In 40986:

Docs: Remove an unnecessary @package tag from the DocBlock for post_preview().

See #41017.

[DrewAPicture]

In 40987:

Docs: Convert an @uses tag in the class DocBlock for Walker_Nav_Menu_Edit to @see.

See #41017.

[DrewAPicture]

In 40988:

Docs: Remove superfluous @package WordPress and @subpackage notations used outside of file headers in a variety of core files.

Per the inline documentation standards for PHP, there should only be one @package and/or @subpackage notation per file, and only in the file header.

See #41017.

[DrewAPicture]

In 40989:

Docs: Remove a few more superfluous @package WordPress and @subpackage notations outside of file headers missed in [40988].

See #41017.

[DrewAPicture]

In 41033:

Docs: Default for the orderby argument in wp_list_categories() is actually 'name', not 'ID'.

Props uicestone.
See #41017.

[DrewAPicture]

In 41034:

Docs: Use a hash notation for the $args parameter to describe the fields argument in the DocBlock for wp_get_post_terms().

Also, the $taxonomy parameter can accept either a string or array of taxonomies.

Props ohryan for the initial tip.
See #41017.

[DrewAPicture]

In 41042:

Docs: Improve the DocBlock summary for WP_Query::parse_orderby().

See #41017.

[johnbillion]

In 41119:

Docs: Correct some inline docs for the Ajax test case.

See #41017

[SergeyBiryukov]

In 41151:

Docs: Use 3-digit, x.x.x style semantic versioning for @since 4.8.0 entries.

See #41017.

[DrewAPicture]

In 41186:

Docs: Remove an unrelated description about post meta from the DocBlock for add_user_meta().

Clean up syntax.

See #41017.

[DrewAPicture]

In 41193:

Docs: Use a third-person singular verb in the summary for _wp_customize_publish_changeset().

Also adding missing @since and @access tags. Introduced in 4.7, see [38810].

See #41017.

[DrewAPicture]

In 41195:

Docs: Use a third-person singular verb in the DocBlock summary for WP_Importer::stop_the_insanity().

Also add a missing @since tag. Introduced in 3.0.0, see [14760].

See #41017.

[johnbillion]

In 41208:

Docs: Correct and improve the documentation for the update_option_new_admin_email() function and the new_admin_email_content filter.

See #41017

[johnbillion]

In 41209:

Docs: Correct and improve the documentation for the send_confirmation_on_profile_email() function and the new_user_email_content filter.

See #41017

[johnbillion]

In 41215:

Docs: Fix various filter documentation.

See #38462, #41017

[johnbillion]

In 41216:

Docs: Add a missing docblock for the the_content_rss filter.

See #38462, #41017

[johnbillion]

In 41221:

General: Fix more instances of inconsistent parameters passed to various filters, plus fix some filter docs.

See #38462, #41017

[johnbillion]

In 41230:

Multisite: Clarify descriptions of the wpmu_signup_blog_notification() and wpmu_signup_user_notification() functions.

See #41017

[johnbillion]

In 41231:

Plugins: Correct and improve docblocks for the various plugin_action_links filters on the Plugins screen.

This also adds a changelog for the removal of the Edit links in [41160].

See #41017
Fixes #38169

[DrewAPicture]

In 41275:

Docs: Add a missing return description for the deprecated get_screen_icon() function.

See #41017.

[DrewAPicture]

In 41282:

Shortcodes: Rename the $func parameter for add_shortcode() to $callback to improve clarity.

See #37222. See #41017.

[johnbillion]

In 41288:

Media: Rename several attachment related parameters from $post_id to $attachment_id for clarity, and improve related
documentation.

See #41017

[DrewAPicture]

In 41308:

Docs: Clarify the expected usage of the $args parameter as an array in the DocBlock for apply_filters_deprecated(), including an example.

See #41017.

[johnbillion]

In 41322:

Docs: Clarify descriptions and parameter types for various user capability checking functions.

See #41017

[johnbillion]

In 41366:

Docs: Clarify some terminology around meta capabilities, primitive capabilities, and roles.

See #41017

[johnbillion]

In 41552:

Multisite: Correct the docs for maybe_add_existing_user_to_blog().

See #41017

[jeremyfelt]

In 41666:

Docs: Clarify docs for hooked count/date updates

See #41017.

[johnbillion]

In 41688:

Docs: Standardise the format used for documenting parameters passed by reference.

See #35974, #41017

[netweb]

Marking as fixed to clear up the 4.9 milestone tickets, any extra commits can be easily appended

[SergeyBiryukov]

In 41914:

Docs: Add @since entry for WP_Automatic_Updater::after_core_update(), introduced in [25841].

See #41017, #29086.

[SergeyBiryukov]

In 41940:

Docs: Reference WP_Comment_Query::__construct() as the source of information on accepted arguments in get_comments() and get_approved_comments().

See #41017.

[johnbillion]

In 41945:

Build/Test tools: Document the return value of WP_UnitTestCase::factory().

See #41017

[johnbillion]

In 41989:

Docs: Correct a class name in the docs for WP_Customize_Manager::post_value().

See #41017

[johnbillion]

In 42007:

Docs: Improve the docs for validate_file() and validate_file_to_edit().

See #42016, #36170, #41017