Fix a variety of phpDoc issues

[DrewAPicture]

• Add DocBlocks where missing
• Clarify param/return types where applicable
• Add missing @since versions

[DrewAPicture]

In 32338:

Clarify accepted types for the $args and $context parameters in WP_Filesystem().

See #32246.

[DrewAPicture]

In 32339:

Add a missing @return tag to the DocBlock for site_admin_notice().

See #32246.

[DrewAPicture]

In 32340:

Add a missing @return tag to the DocBlock for `uninstall_plugin().

See #32246.

[DrewAPicture]

In 32341:

Add a missing DocBlock for wp_caption_input_textarea().

See #32246.

[DrewAPicture]

In 32352:

Fix documentation syntax and formatting for the media_sideload_image() DocBlock.

See #32246.

[DrewAPicture]

In 32451:

Add a description to the hook documentation for the created_$taxonomy action to clarify the dynamic portion of the hook name.

See #32246.

[DrewAPicture]

In 32452:

Ensure the optional parameter in get_object_taxonomies() is documented as such.

See #32246.

[DrewAPicture]

In 32453:

Fix a wide variety of syntactical, spacing, wording, and other issues in wp-includes/taxonomy.php.

See #32246.

[DrewAPicture]

In 32559:

Add missing argument descriptions for the $args hash notation in wp_xmlrpc_server->wp_getUsersBlogs().

See #32246.

[DrewAPicture]

In 32560:

Use a valid parameter type of string for the $name parameter in the xmlrpc_call hook docs.

See #32246.

[DrewAPicture]

In 32561:

Fix some inline documentation syntax in the DocBlock for wp_xmlrpc_server->minimum_args().

See #32246.

[DrewAPicture]

In 32562:

Fix inline documentation syntax in the DocBlock for wp_xmlrpc_server->_prepare_taxonomy().

See #32246.

[DrewAPicture]

In 32563:

Add missing parameter and return descriptions to the DocBlock for wp_xmlrpc_server->_convert_date().

See #32246.

[DrewAPicture]

In 32564:

Add missing parameter and return descriptions to the DocBlock for wp_xmlrpc_server->_convert_date_gmt().

See #32246.

[DrewAPicture]

In 32565:

Add missing or incomplete argument and return descriptions for wp_xmlrpc_server->wp_editPost().

Also includes many small syntax fixes for inline documentation throughout the file.

See #32246.

[DrewAPicture]

In 32572:

Add missing argument descriptions in the DocBlock for wp_xmlrpc_server->wp_deletePost().

See #32246.

[DrewAPicture]

In 32573:

Convert the $args parameter documentation in wp_xmlrpc_server->wp_getPost() into a hash notation.

See #32246.

[DrewAPicture]

In 32574:

Define the default values for the $fields parameter in the xmlrpc_default_post_fields hook docs.

See #32246.

[DrewAPicture]

In 32575:

Convert the $args parameter for wp_xmlrpc_server->wp_getPosts() into a hash notation.

Also considates documentation to the argument descriptions themselves.

See #32246.

[DrewAPicture]

In 32576:

Convert the $args parameter documentation in wp_xmlrpc_server->wp_newTerm() into a hash notation.

Also clarifies the return description.

See #32246.

[DrewAPicture]

In 32577:

Convert the $args parameter documentation in wp_xmlrpc_server->wp_editTerm() to a hash notation.

Also clarifies the return description.

See #32246.

[DrewAPicture]

In 32578:

Convert the $args parameter documentation in wp_xmlrpc_server->wp_deleteTerm() into a hash notation.

Also clarifies the return description.

See #32246.

[DrewAPicture]

In 32579:

In most wp_xmlrpc_server methods that accept an array of arguments, the argument order is important.

With the converstion to hash notations from simple lists in the inline documentation, it's especially important to make that requirement clear.

See #32246.

[DrewAPicture]

In 32581:

Convert the $args parameter documentation for wp_xmlrpc_server->wp_newPost() into a hash notation.

Also adds more in-depth documentation and a link for information on enclosures.

See #32246.

[DrewAPicture]

In 32582:

Add missing $args parameter descriptions for wp_xmlrpc_server->wp_getTerm().

Also clarifies the return description.

See #32246.

[DrewAPicture]

In 32583:

Add missing argument descriptions for the $args parameter in wp_xmlrpc_server->wp_getTerms().

Also clarifies the return description.

See #32246.

[DrewAPicture]

In 32584:

Add missing argument descriptions for the $args parameter in wp_xmlrpc_server->wp_getTaxonomy().

Also clarifies the return description.

See #32246.

[DrewAPicture]

In 32585:

Add missing argument descriptions for the $args parameter in wp_xmlrpc_server->wp_getTaxonomies().

Also documents missing $filter and $fields arguments and associated descriptions, and clarifies the return description.

See #32246.

[DrewAPicture]

In 32586:

Clarify that wp_xmlrpc_server->wp_getTaxonomies() returns an IXR_Error instance on failure.

See #32246.

[DrewAPicture]

In 32591:

Fix inline documentation syntax in wp_xmlrpc_server.

See #32246.

[DrewAPicture]

In 32660:

Add missing return descriptions and fix formatting of inline documentation introduced in [32644].

See #25408. See #32246.

[DrewAPicture]

In 32661:

Fix formatting and add a missing return description for inline documentation introduced in [32644] for WP_Links_List_Table.

See #25408. See #32246.

[DrewAPicture]

In 32662:

Fix formatting and add missing return descriptions for inline documenation introduced in [32644] for WP_List_Table.

Also fixes an error introduced in [32661] for WP_Links_List_Table.

See #25408. See #32246.

[DrewAPicture]

In 32663:

Fix formatting and add a missing return description for inline documentation introduced in [32644] for WP_Media_List_Table.

See #25408. See #32246.

[DrewAPicture]

In 32664:

Fix formatting and add missing return descriptions for inline documentation introduced in [32644] for WP_MS_Sites_List_Table.

See #25408. See #32246.

[DrewAPicture]

In 32665:

Fix syntax and add a missing return description for inline documentation introduced in [32644] for WP_MS_Themes_List_Table.

See #25408. See #32246.

[DrewAPicture]

In 32666:

Fix formatting and add missing return descriptions for inline documentation introduced in [32644] for WP_MS_Users_List_Table.

See #25408. See #32246.

[DrewAPicture]

In 32667:

Fix formatting and add a missing return description for inline documentation introduced in [32644] for WP_Plugins_List_Table.

See #25408. See #32246.

[DrewAPicture]

In 32668:

Fix syntax and add missing return descriptions for inline documentation introduced in [32644] for WP_Posts_List_Table.

See #25408. See #32246.

[DrewAPicture]

In 32669:

Fix syntax and add missing return descriptions for inline documentation introduced in [32644] for WP_Terms_List_Table.

See #25408. See #32246.

[DrewAPicture]

In 32670:

Fix syntax and add a missing return description for inline documentation introduced in [32644] for WP_Users_List_Table.

See #25408. See #32246.

[DrewAPicture]

In 32926:

Document default values for optional arguments in edit_term_link().

See #32246.

[DrewAPicture]

In 33216:

Fix missing or inconsistent parameter descriptions for constructors in WP_Customize_Control, WP_Customize_Color_Control, WP_Customize_Media_Control, WP_Customize_Image_Control, WP_Customize_Background_Image_Control, WP_Customize_Site_Icon_Control, WP_Customizer_Header_Image_Control, and WP_Customize_Nav_Menu_Item_Control.

See #32891. See #32246.

[DrewAPicture]

In 33222:

Add a missing $html parameter variable in the hook docs for the style_loader_tag filter.

See #32246. See #32891.

[DrewAPicture]

In 33229:

Fix inline documentation syntax for the language_attributes() DocBlock.

See #32246. See #32891.

[DrewAPicture]

In 33230:

Remove now-unnecessary inline @see tag from the DocBlock for wp_dropdown_languages().

See #32246.

[DrewAPicture]

In 33235:

Remove a now-unnecessary inline @see tag from the description for add_rewrite_endpoint().

See #32246.

[DrewAPicture]

In 33237:

Properly mark the $query_var parameter as optional in the DocBlock for WP_Rewrite->add_endpoint().

See #32246. See #32891.

[DrewAPicture]

In 33238:

Fix formatting in the DocBlock for _split_shared_term().

See #32246. See #32891.

[DrewAPicture]

In 33247:

Fix a typo in the hook docs summary for the send_pass_change_email filter.

See #32246.

[DrewAPicture]

In 33248:

Fix the same typo again in the hook doc summary for the send_pass_change_email filter.

I speak English, I do.

See #32246.

[DrewAPicture]

In 33272:

Update the descriptions for get_front_page_template() and get_comments_popup_template() to reference the correct dynamic hook names.

Part props @birgire.

Fixes #32989. See #32246.

[DrewAPicture]

In 33273:

Docs: Clarify the hook docs for the {$type}_template hook to mention that non-alphanumeric characters delimiting words will also be removed from the passed $type parameter.

Also remove a now-unnecessary inline @see tag from the return description.

See #32246. See #32989.

[DrewAPicture]

In 33274:

Docs: Update the DocBlock descriptions for a variety of template functions to better reflect that the dynamic $type_template hook can be used to filter the template path.

It's important to reference the actual dynamic hook name instead of an alias for purposes of auto-linking in the Code Reference.

Affects the docs for:

• get_index_template()
• get_404_template()
• get_archive_template()
• get_post_type_archive_template()
• get_author_template()
• get_category_template()
• get_tag_template()
• get_taxonomy_template()
• get_date_template()
• get_home_template()
• get_page_template()
• get_paged_template()
• get_search_template()
• get_single_template()
• get_singular_template()
• get_attachment_template()

See #32246.

[DrewAPicture]

In 33318:

Update the description for get_the_category() with helpful information for the proper function to use for custom taxonomies.

Also adds a missing return description.

See #32246.

[DrewAPicture]

In 33664:

Docs: Mark the $notify parameter in the DocBlock for wp_new_user_notification() as optional, and provide additional context on the difference between the accepted values.

See [33620] and [33023] for background.

See #32246.

[DrewAPicture]

In 33670:

Docs: Add a missing summary to the DocBlock for wp_media_upload_handler().

See #32246.

[DrewAPicture]

In 33686:

Docs: Fix some minor inline documentation syntax issues in the hook docs for the post_edit_category_parent_dropdown_args filter, introduced in [33682].

See #32246. See #33026.

[DrewAPicture]

In 33712:

Docs: Fix a minor alignment issue in the DocBlock for get_pagenum_link().

See #32246.

[DrewAPicture]

In 33715:

Docs: Add better documentation for all accepted values for the fields argument in get_terms().

See #32246.

[DrewAPicture]

In 33720:

Docs: Improve pared formatting of the oEmbed providers tables by removing the unrecognized first and last rows in the hook docs for the oembed_providers filter.

See #32246.

[DrewAPicture]

In 33882:

Docs: Add inline DocBlocks for the require_once() calls that now bring in top-level HTTP API functionality and HTTP API classes.

Classes brought in from separate files now include:

• WP_Http
• WP_Http_Streams
• WP_Http_Curl
• WP_HTTP_Proxy
• WP_Http_Cookie
• WP_Http_Encoding

See #33413. See #32246.

[DrewAPicture]

In 34225:

Docs: Add more complete documentation for top-level object cache functionality.

Adds some @see tags for corresponding WP_Object_Cache methods to DocBlocks for top-level functions. Also adds a standard description for the @global tags, spacing for parameter docs readability, and finally, properly marks optional parameters as such.

See #32246.

[DrewAPicture]

In 34226:

Docs: Remove an errant change made to a _deprecated_function() call in wp_cache_reset() introduced in [34225].

See #32246.

[DrewAPicture]

In 34227:

Docs: Improve documentation for the WP_Object_Cache class.

Spaces out parameter documentation for readability, fixes some minor syntactical issues, and adds some missing @access tags or reorders tags according to the PHP docs standards.

Also, documents &$found, the fourth parameter for the get() method, and adds missing parameter and return descriptions for the _exists() utility method.

See #32246.

[DrewAPicture]

In 34229:

Docs: Remove markdown from the DocBlock summary for WP_List_Table::get_primary_column(), introduced in [34166].

The PHP inline documentation standards for ​summaries call for not using an markup or markdown. Also, using the full Class::method() in this context allows for better clarity in what is being referenced.

See #33854. See #32246.

[DrewAPicture]

In 34230:

Docs: Make a minor adjustment to the description syntax for the optional $comment argument in the DocBlock for comment_link(), introduced in [34071].

See #33638. See #32246.

[DrewAPicture]

In 34235:

Docs: Add a changelog entry for the addition of 'wp-admin', 'wp-content', and 'wp-includes' as reserved names for the subdirectory_reserved_names filter docs.

The new names were introduced in [33952].

See #33615. See #32246.

[DrewAPicture]

In 34236:

Docs: Fix some syntactical issues with the DocBlock for the WP_Theme->update property, introduced in [33957].

Adds an @since.

See #33491. See #32246.

[DrewAPicture]

In 34237:

Docs: Add changelog entries for parameters where WP_Comment object support was added in [33961].

See #33638. See #32246.

[brentvr]

add_query_arg xxs reminder

[brentvr]

Added 32246.diff​ which gives two common examples of passing arguments to add_query_arg as well as a note about escaping.

[DrewAPicture]

In 34264:

Docs: Add a reminder to the DocBlock description for add_query_arg() mentioning that the output is not escaped by default.

Props brentvr for the initial patch. (first props!)
See #33912. See #32246.

[DrewAPicture]

In 34285:

Docs: Fix some syntactical isses in the DocBlock for get_queried_object().

Also add descriptions for the return and the WP_Query global.

See #32246.

[DrewAPicture]

In 34286:

Docs: Fix some syntactical issues in the documentation for get_queried_object_id().

Adds descriptions for the global WP_Query instance and the return.

See #32246.

[DrewAPicture]

In 34287:

Docs: Fix some syntactical issues in the DocBlock for set_query_var().

Adds descriptions for the global WP_Query instance and the $value parameter.

See #32246.

[DrewAPicture]

In 34355:

Docs: Add a description for the documented use of the $wpdb global in _prime_comment_caches().

See #8071. See #32246.

[DrewAPicture]

In 34368:

Docs: Move a duplicate hook comment accidentally left behind when its corresponding filter was relocated in [31765].

See #31443. See #32246.

[DrewAPicture]

In 34384:

Docs: Include 'wp-json' in the 4.4.0 changelog entry for the subdirectory_reserved_names filter.

'wp-json' was appended to the reserved names list in [34375].

See #33789. See #32246.

[DrewAPicture]

In 34386:

Docs: Add a changelog entry to WP_Widget_Categories for non-category support, added in [34376].

See #21165. See #32246.

[DrewAPicture]

In 34388:

Docs: Fix some syntactical issues and add missing parameter and return descriptions to the DocBlock for the WP_User::__isset() magic method.

See #32246.

[DrewAPicture]

In 34389:

Docs: Fix some syntactical issues and add missing parameter and return descriptions to the DocBlock for the WP_User::__get() magic method.

See #32246.

[DrewAPicture]

In 34422:

Docs: Clarify the class DocBlock summary for WP_Screen.

See #32246.

[DrewAPicture]

In 34431:

Docs: Clarify the class DocBlock summary for WP_Widget_Categories.

See #32246.

[DrewAPicture]

In 34482:

Docs: Split the DocBlock summary for __() into a summary and description.

Also, notate the default value for the optional $domain parameter.

See #32246.

[DrewAPicture]

In 34483:

Docs: Clarify the file header summary for wp-includes/l10n.php and add the version it was introduced.

See #32246.

[DrewAPicture]

In 34484:

Docs: Fix the summary for get_locale().

Also update the description to properly link up hook references with inline @see tags.

See #32246.

[DrewAPicture]

In 34485:

Docs: Link up a hook reference with an inline @see tag in the return description for get_locale().

Missed in [34484].

See #32246.

[DrewAPicture]

In 34489:

Docs: Add a summary, version, and @access tag to the property DocBlock for WP_Locale->number_format.

See [5308] for where the property was initially introduced.
See [31083] for where the property was actually declared.

Props brentvr.
See #30224. See #32246.

[DrewAPicture]

In 34490:

Docs: Add a summary, version, and @access tag to the property DocBlock for Custom_Background->updated.

See [13765] for where the property was initially introduced.
See [30186] for where the property was actually declared.

Props brentvr.
See #30224. See #32246.

[DrewAPicture]

In 34491:

Docs: Add a summary, version, and @access tag to the property DocBlock for Custom_Image_Header->updated.

See [14907] for where the property was initially introduced.
See [30187] for where the property was actually declared.

Props brentvr.
See #30224. See #32246.

[DrewAPicture]

In 34493:

Docs: Add a summary, version, and parameter and return descriptions to the DocBlock for WP_Filesystem_FTPext::get_contents().

Also reverses the return types as string is expected, false is the outlier.

See [30978].

See #30989. See #32246.

[DrewAPicture]

In 34495:

Docs: Add a summary, version, and parameter and return descriptions to the DocBlock for WP_Filesystem_ftpsockets::get_contents().

Also reverses the return types as string is expected, false is the outlier.

See [30978].

See #30989. See #32246.

[DrewAPicture]

In 34497:

Docs: Mark the optional $upgrader parameter as such and add a description in the DocBlock for Language_Pack_Upgrader::async_upgrade().

See [32655].

See #30989. See #32246.

[DrewAPicture]

In 34499:

Docs: Standardize and clarify class DocBlocks for all of the Upgrade API classes.

Standardizes summaries and tags for the following classes:

• WP_Upgrader
• Plugin_Upgrader
• Theme_Upgrader
• Language_Pack_Upgrader
• Core_Upgrader
• File_Upload_Upgrader
• WP_Automatic_Updater

See #32246.

[DrewAPicture]

In 34553:

Docs: Add a missing summary, version, and tag descriptions to the DocBlock for WP_Widget_Text::widget().

See #32246.

[DrewAPicture]

In 34560:

Docs: Improve the method docs for the widget(), update(), form(), and __construct() methods in the WP_Widget base class.

See #34013. See #32246.

[DrewAPicture]

In 34565:

Docs: Fix the syntax for a mid-file sectional comment in wp-admin/includes/dashboard.php.

See #32246.

[DrewAPicture]

In 34589:

Docs: Adjust the table of providers in the hook doc for oembed_providers to use "No" instead of "!" to signify lack of SSL support.

When displayed in the Code Reference, the "!" doesn't convey enough information.

See #32246. See #28507.

[DrewAPicture]

In 34592:

Docs: Add missing parameter documentation for $profileuser in the hook doc for show_password_fields, added in [11302].

Also adds a changelog entry for when the parameter was introduced.

See #32246.

[DrewAPicture]

In 34593:

Docs: Fix a minor typo from [34592]. Meant to be past-tense, not present.

See #32246.

[johnbillion]

In 34597:

Remove the unnecessary horizontal rules in the oEmbed providers table to tidy up the Code Reference.

See #32246

[DrewAPicture]

In 34635:

Docs: Fix some syntatical issues in the DocBlock for WP::send_headers() following [34632].

See #20226. See #32246.

[DrewAPicture]

In 34644:

Docs: Slightly improve the readability of the data table in the DocBlock description for the oembed_providers hook by centering the HTTPS column.

See #32246.

[DrewAPicture]

In 34647:

Docs: Improve the hook documentation for the plugins_api filter.

Standardizes the hook doc summary and expands on expected behavior when short-circuiting the request, which is dependent on the $action type.

See #34035. See #32246.

[DrewAPicture]

In 34651:

Docs: Improve the hook documentation for the themes_api filter.

Standardizes the hook doc summary and expands on expected behavior when short-circuiting the request, which is dependent on the $action type.

Also updates the expected types on the $override parameter.

See #34036. See #32246.

[DrewAPicture]

In 34652:

Docs: Improve the hook documentation for the plugins_api_args filter.

Standardizes the hook doc summary and expands on the expected type for the $args parameter.

See #34035. See #32246.

[johnbillion]

In 34665:

Add a missing @param doc for confirm_another_blog_signup().

See #32246

[jeremyfelt]

In 34676:

Docs: Clarify $user parameter documentation in wpmu_validate_blog_signup.

See #32246.

[DrewAPicture]

In 34706:

Docs: Add an @see reference for the "use-instead-of" function in the DocBlock for force_ssl_login(), deprecated in [34700].

See #34011. See #32246.

[DrewAPicture]

In 34712:

Docs: Mark a few optional parameters as such in wp-includes/rewrite-functions.php.

See #32246.

[DrewAPicture]

In 34717:

Docs: There are quite alot of typos in core inline comments.

See #32246.

[DrewAPicture]

In 34725:

Docs: Document declaration of the $submenu_file global in wp-admin/menu-header.php.

See #24531. See #32246.

[DrewAPicture]

In 34746:

Docs: Update the argument descriptions for $child_of and $hierarchical in get_pages() to more closely reflect expected behavior.

See #18701. See #32246.

[DrewAPicture]

In 34782:

Docs: Fix the placement and ordering of some @since tags following [34780].

See #12133. See #32246.

[DrewAPicture]

In 34818:

Docs: Document the plugin data array returned by get_plugin_data() with a hash-notation.

See #32246.

[DrewAPicture]

In 34821:

Docs: Add missing summaries for three deprecated admin functions: dropdown_categories(), dropdown_link_categories(), and wp_dropdown_cats().

See #32246.

[DrewAPicture]

In 34822:

Docs: Add missing method summaries for the deprecated WP_User_Search class, including prepare_query(), query(), prepare_vars_for_template_usage(), do_paging(), and get_results().

See #32246.

[DrewAPicture]

In 34823:

Docs: Add missing DocBlock summaries for a multitude of functions in wp-admin/includes/media.php.

See #32246.

[DrewAPicture]

In 34824:

Docs: Add missing summaries for functions in wp-admin/includes/misc.php.

Also restructures the summary for update_home_siteurl().

See #32246.

[DrewAPicture]

In 34825:

Docs: Add missing DocBlock summaries to three functions in wp-admin/includes/plugin.php.

See #32246.

[DrewAPicture]

In 34826:

Docs: Add missing DocBlock summaries for five functions in wp-admin/includes/template-functions.php.

See #32246.

[DrewAPicture]

In 34827:

Docs: Add a missing DocBlock summary for wp_list_widget_controls_dynamic_sidebar().

See #32246.

[johnbillion]

In 34836:

Include post__in as a value available to the orderby parameter in the docs for WP_Query::parse_query().

See #32246

[DrewAPicture]

In 34843:

Docs: Adjust the line wrap indentation on the $link parameter description for the wp_post_revision_title_expanded hook, introduced in [34842].

See #32246.

[DrewAPicture]

In 34992:

Docs: Indent an example comment tree in the DocBlock for Walker_Comment::display_element() so it can be properly parsed in Markdown for the Code Reference.

See #32246.

[DrewAPicture]

In 34993:

Docs: Fix wrapping and syntax for a multi-comment in Walker_Comment::display_element().

See #32246.

[DrewAPicture]

In 35004:

Docs: Fix some minor formatting in the $query_args parameter description for the filter doc.

See #8243. See #32246.

[DrewAPicture]

In 35021:

Docs: Fix some syntactical issues in property DocBlocks for WP_List_Table.

See #32246.

[DrewAPicture]

In 35027:

Docs: Wrap a couple of hook name references in inline @see tags in the hook docs for custom_menu_order and menu_order.

Inline @see tags in the context of hooks are parsed as links to hook pages in the Code Reference.

See #32246.

[DrewAPicture]

In 35046:

Docs: Normalize spacing in the $attr hash notation for gallery_shortcode() following [35045].

See #34257. See #32246.

[DrewAPicture]

In 35056:

Docs: Fix syntax and properly mark optional parameters as such in the DocBlock for get_image_send_to_editor().

Also fixes the return description, and adds the $size default value, missed in [35055].

See #34257. See #32246.

[DrewAPicture]

In 35057:

Docs: Fix the syntax for marking parameters optional and add defaults in the DocBlock for wp_get_attachment_link().

See #32246.

[DrewAPicture]

In 35059:

Docs: Normalize spacing in the image_send_to_editor hook doc following [35058].

See #34257. See #32246.

[DrewAPicture]

In 35061:

Docs: Fix hash notation syntax for the $sizes[ $size ] section in the DocBlock for WP_Image_Editor_GD::multi_resize().

See #32246.

[DrewAPicture]

In 35062:

Docs: Fix hash notation syntax for the $sizes[ $size ] section in the DocBlock for WP_Image_Editor_Imagick::multi_resize().

See #32246.

[DrewAPicture]

In 35063:

Docs: Re-clarify the $sizes[ $size ] section of the hash notations for WP_Image_Editor_GD::multi_resize() and WP_Image_Editor_Imagick::multi_resize() as not fully-optional.

The $width value is optional if $height is specified, and vice versa. The $crop value is always optional and defaults to false.

Props dh-shredder.
See #32246. See [35061] and [35062].

[DrewAPicture]

In 35064:

Docs: Improve documentation for get_site_icon_url(), introduced in [32994].

Adds a missing @since version, fixes optional parameter syntax, adds default values, and fixes the return description.

See #32246.

[DrewAPicture]

In 35066:

Docs: Normalize spacing in the wp_get_attachment_link hook doc following [35065].

See #34257. See #32246.

[DrewAPicture]

In 35073:

Docs: Normalize spacing in the post_thumbnail_html hook doc following [35072].

See #34257. See #32246.

[DrewAPicture]

In 35074:

Docs: The $size parameters in the begin_fetch_post_thumbnail_html and end_fetch_post_thumbnail_html hooks can also accept an array (already supported).

See #34257. See #32246. See [35070] and [35071].

[DrewAPicture]

In 35079:

Docs: Normalize spacing in the DocBlock for get_image_send_to_editor() following [35056].

See #34257. See #32246.

[DrewAPicture]

In 35080:

Docs: Specify the default image size in the $size parameter description for the image_send_to_editor hook.

See #34257. See #32246. See [35058].

[johnbillion]

In 35085:

Add missing @since docs for the filters in wp-includes/embed-template.php

See #32522, #32246

[johnbillion]

In 35090:

Add missing @since params and update the docs for site_icon_url() and has_site_icon().

See #32246

[johnbillion]

In 35149:

Improve the docs for the $expiration parameter in set_transient(), set_site_transient(), and associated filters.

See #32246

[DrewAPicture]

In 35157:

Docs: Add missing file headers to two Toolbar API files: wp-includes/admin-bar.php and wp-includes/class-wp-admin-bar.php.

See #32246.

[DrewAPicture]

In 35169:

Docs: Fix third-person singular verbs for summaries in wp-admin/includes/bookmarks.php.

Also adds some missing parameter, return, and global descriptions, and one missing summary.

See #32246.

[DrewAPicture]

In 35170:

Docs: Add missing descriptions for the $wpdb global in DocBlocks all the places.

See #32246.

[DrewAPicture]

In 35240:

Docs: Improve the hook doc for the get_post_status filter, introduced in [35233].

Also adds a missing parameter description for $post.

See #23458. See #32246.

[DrewAPicture]

In 35287:

Docs: The MINUTE_IN_SECONDS, HOUR_IN_SECONDS, DAY_IN_SECONDS, WEEK_IN_SECONDS, MONTH_IN_SECONDS, and YEAR_IN_SECONDS constants were introduced in 3.5.

See [21996]. See #32246.

[DrewAPicture]

In 35290:

Docs: Correction: MONTH_IN_SECONDS was added in 4.4.0.

Props swissspidy.
See [33698]. See #32246.

[DrewAPicture]

In 35296:

Docs: Fix up DocBlock syntax for the now-deprecated wp_title().

See #32246.

[DrewAPicture]

In 35297:

Docs: Improve vague changelog entries for functions and hooks where arguments were deprecated in [35294].

See #31078. See #32246.

[DrewAPicture]

In 35298:

Docs: Update the hook doc for the pre_get_document_title filter to explain what value is filterable rather than why the value is filterable :-)

The hook was introduced in [35294].

See #31078. See #32246.

[DrewAPicture]

In 35300:

Docs: Fix indentation and improve usefulness of inline comments surrounding the if/elseif conditions for assigning document titles in wp_get_document_title().

See #31078. See #32246.

[DrewAPicture]

In 35301:

Docs: Adjust syntax in the hook doc summaries for the document_title_separator and document_title_parts filters, introduced in [35294].

See #31078. See #32246.

[DrewAPicture]

In 35303:

Docs: Add translator comments for two _deprecated_argument() calls added to get_wp_title_rss() and wp_title_rss() in [35294].

See #31078. See #32246.

[DrewAPicture]

In 35375:

Docs: Syntax fixes for deprecating WP_Http::parse_url().

See #32246.

[DrewAPicture]

In 35393:

Docs: Add missing DocBlocks for the $type and $sidebar_id properties, and summaries for the to_json() and render_content() methods in WP_Widget_Area_Customize_Control.

See #32246.

[johnbillion]

In 35413:

List the possible values for the dynamic portion of the {type}_template hook.

See #14310, #32246

[DrewAPicture]

In 35503:

Docs: Add a missing return description for _get_custom_object_labels(), a private core helper function.

See #32246.

[DrewAPicture]

In 35787:

Docs: Fix mid-file separator syntax in wp-includes/wp-db.php.

Props liamdempsey.
See #32246.

[DrewAPicture]

In 35844:

Docs: Move the hook doc for the view_mode_post_types filter to directly precede the apply_filters() line.

See #32246.

[swissspidy]

In 35885:

Docs: Fix some minor DocBlock alignment issues.

See #32246.

[johnbillion]

In 35906:

Remove a redundant @param tag from the_taxonomies().

See #32246

[johnbillion]

In 35907:

Add a missing @param doc to wp_update_term_count().

See #32246

[johnbillion]

In 35908:

Correct the name of the @param doc for WP_Query::parse_tax_query().

See #32246

[johnbillion]

In 35909:

Add missing @param doc to wp_check_password() and update the check_password filter docs.

See #32246

[johnbillion]

In 35912:

Add missing variadic markers to the optional parameters of do_action() and apply_filters().

See #32246

[johnbillion]

In 35913:

Add missing @param doc to wp_hash().

See #32246

[johnbillion]

In 35914:

Add missing @param docs to wp_safe_redirect() and wp_sanitize_redirect().

See #32246

[johnbillion]

In 35915:

Correct a parameter name in the @param docs for get_home_url().

See #32246

[johnbillion]

In 35916:

Correct some @param doc names in the WP_Tax_Query and WP_User_Query classes.

See #32246

[johnbillion]

In 35918:

Correct the position of the $alt parameter's @param doc in image_add_caption().

See #32246

[SergeyBiryukov]

In 35920:

Docs: Capitalize 'URL' correctly in the_guid() DocBlock. Fix a typo.

See #32246.

[DrewAPicture]

In 35926:

Docs: Document the $id parameter for Walker_CategoryDropdown::start_el(), which is implemented by Walker but unused in the subclass method.

See #32246.

[DrewAPicture]

In 35927:

Docs: Document the $id parameter for Walker_Comment::start_el(), which is implemented by Walker but unused in the subclass method.

See #32246.

[DrewAPicture]

In 35928:

Docs: Add a missing description for the $id parameter in the DocBlock for Walker_PageDropdown::start_el(), which is implemented by Walker but unused by the subclass method.

Also marks the other optional parameters as such.

See #32246.

[DrewAPicture]

In 35929:

Docs: Add more complete property and method documentation for Walker_Page.

• Adds missing DocBlock summaries
• Adds missing @param descriptions
• Marks some optional parameters as such
• Reorders some DocBlock tags

See #32246.

[DrewAPicture]

In 35930:

Docs: Add missing parameter and return descriptions to the DocBlock for WP_Http_Curl::stream_headers().

See #32246.

[DrewAPicture]

In 35937:

Docs: Add missing parameter and return descriptions to the DocBlock for WP_Http_Curl::stream_body().

See #32246.

[DrewAPicture]

In 35938:

Docs: Add missing parameter documentation for the $args parameter in the DocBlock for WP_Http_Curl::test().

See #32246.

[DrewAPicture]

In 35939:

Docs: Remove an extra 'arguments' introduced in [35938].

See #32246.

[DrewAPicture]

In 35940:

Docs: Add missing parameter documentation for the $args parameter in the DocBlock for WP_Http_Streams::test().

See #32246.

[DrewAPicture]

In 35941:

Docs: Add missing parameter and return descriptions to the DocBlock for WP_Rewrite::iis7_url_rewrite_rules().

See #32246.

[DrewAPicture]

In 35954:

Docs: Add variadic markers to the optional $object_id parameter notation for WP_User::has_cap().

See #32246.

[DrewAPicture]

In 35955:

Docs: Add missing summaries and @since versions to DocBlocks for the _get_display_callback(), _get_update_callback(), and _get_form_callback() methods in WP_Widget.

Introduced in [10764].

See #32246.

[DrewAPicture]

In 35956:

Docs: Add a missing summary and @since version to the DocBlock for wp_xmlrpc_server::serve_request().

Introduced in [11789].

See #32246.

[DrewAPicture]

In 35957:

Docs: Add a missing notation for the $args parameter in the DocBlock for wp_xmlrpc_server::_multisite_getUsersBlogs().

Also adds a missing @since version. The method was introduced in [12852].

See #32246.

[DrewAPicture]

In 35961:

Docs: Add missing property and method summaries in DocBlocks for Walker_PageDropdown.

See #32246.

[DrewAPicture]

In 35962:

Docs: Add missing notations for the unused $args parameter in the blogger_getTemplate() and blogger_setTemplate() methods in wp_xmlrpc_server.

See #32246.

[DrewAPicture]

In 35963:

Docs: Add a missing summary, @since version, and parameter descriptions to the DocBlock for wp_xmlrpc_server::add_enclosure_if_new().

Introduced in [10383].

See #32246.

[DrewAPicture]

In 35964:

Docs: Add a missing summary, @since version, and parameter descriptions to the DocBlock for wp_xmlrpc_server::pingback_error().

Introduced in [23329]. Also corrects return descriptions for two deprecated methods.

See #32246.

[DrewAPicture]

In 35965:

Docs: Add missing DocBlocks, including summaries and @since versions, to the __construct() and init() methods in WP_Scripts.

See #32246.

[DrewAPicture]

In 35966:

Docs: Mark the upgrade_XX() functions to be ignored from parsing for the Code Reference.

There is no great value in generating reference pages for these funcitons as they explicitly serve a core-only purpose.

See #32246.

[DrewAPicture]

In 35967:

Docs: Add a missing summary to the DocBlock for WP_Locale::rtl_src_admin_notice().

See #32246.

[DrewAPicture]

In 35968:

Docs: Add missing parameter descriptions to the DocBlock for WP_Query::set_found_posts().

See #32246.

[johnbillion]

In 35969:

Correct a parameter name for the allow_password_reset filter so its entry on developer.wordpress.org displays correctly.

See #32246

[swissspidy]

In 35970:

Docs: Correct a parameter name for the do_mu_upgrade filter.

See #32246.

[swissspidy]

In 35971:

Docs: Correct a parameter name for the allow_subdirectory_install filter.

See #32246.

[swissspidy]

In 35972:

Docs: Correct a parameter name for the validate_current_theme filter.

See #32246.

[swissspidy]

In 35973:

Docs: Correct a parameter name for the force_filtered_html_on_import filter.

See #32246.

[swissspidy]

In 35974:

Docs: Correct a parameter name for the press_this_redirect_in_parent filter.

See #32246.

[swissspidy]

In 35975:

Docs: Clarify the return value for wp_create_categories().

See #32246.

[swissspidy]

In 35976:

Docs: Document the default value for the $validate parameter in the validate_current_theme hook docs.

See #32246.

[DrewAPicture]

In 35979:

Docs: Clarify the summary and add missing parameter notations to the DocBlock for _wp_delete_tax_menu_item().

See #32246.

[DrewAPicture]

In 35980:

Docs: Add missing parameter and return notations to the DocBlock for _wp_sanitize_utf8_in_redirect().

See #32246.

[DrewAPicture]

In 35981:

Docs: Add a missing notation for the $args parameter in the DocBlock for wp_get_post_revisions().

See #32246.

[DrewAPicture]

In 35982:

Docs: Add a missing summary, parameter, and return notations to the DocBlock for strip_shortcode_tag().

Introduced in [18952].

See #32246.

[DrewAPicture]

In 35985:

Docs: Add a missing summary and @since version to the DocBlock for _maybe_update_core().

Introduced in [10583].

See #32246.

[DrewAPicture]

In 35986:

Docs: Add missing parameter and return descriptions to the DocBlock for _wp_get_user_contactmethods().

See #32246.

[DrewAPicture]

In 35989:

Docs: Add a missing summary, @since version, and parameter descriptions to the DocBlock for _register_widget_update_callback().

Introduced in [10798].

See #32246.

[DrewAPicture]

In 35990:

Docs: Fix syntax for marking parameters optional in the DocBlock for is_active_widget().

See #32246.

[DrewAPicture]

In 35991:

Docs: Add a missing summary, @since version, and parameter descriptions in the DocBlock for _register_widget_form_callback().

See #32246.

[DrewAPicture]

In 35992:

Docs: Add a better summary, missing @since version, parameter and return descriptions to the DocBlock for _get_widget_id_base().

Introduced in [11484].

See #32246.

[DrewAPicture]

In 35993:

Docs: Add missing parameter notations to the DocBlock for get_author_posts_url().

See #32246.

[DrewAPicture]

In 36009:

Docs: Add a missing notation for the $bookmark_id parameter in the DocBlock for clean_bookmark_cache().

See #32246.

[DrewAPicture]

In 36010:

Docs: Add a missing summary, description, and @since version to the DocBlock for wp_redirect_admin_locations().

Introduced in [19880].

See #32246.

[DrewAPicture]

In 36011:

Docs: Fix the syntax for the get_previous_post_link() DocBlock to ensure it's read and parsed as such instead of as a multi-line comment.

See #32246.

[DrewAPicture]

In 36012:

Docs: Add a missing notation for the $context parameter in the DocBlock for _nx_noop().

See #32246.

[DrewAPicture]

In 36013:

Docs: Add missing parameter and return descriptions to the DocBlocks for _wp_object_name_sort_cb() and _wp_object_count_sort_cb(), both uasort() callbacks.

See #32246.

[DrewAPicture]

In 36017:

Docs: Add missing DocBlocks for mb_substr() and _mb_substr().

Both will be ignored from parsing as and serve as compat functions for PHP's mb_substr(), which is not enabled by default.

Introduced in [17621].

See #32246.

[DrewAPicture]

In 36018:

Docs: Fix inline comment syntax in _mb_substr(), an internal compat method for mb_substr().

See #32246.

[DrewAPicture]

In 36019:

Docs: Add missing DocBlocks for mb_strlen() and _mb_strlen().

Both will be ignored from parsing as and serve as compat functions for PHP's mb_strlen(), which is not enabled by default.

Introduced in [32114].

See #32246.

[DrewAPicture]

In 36020:

Docs: Fix inline comment syntax in _mb_strlen(), an internal compat method for mb_strlen().

See #32246.

[DrewAPicture]

In 36021:

Docs: Add missing DocBlocks for hash_hmac() and _hash_hmac().

Both will be ignored from parsing as and serve as compat functions for PHP's hash_hmac().

Introduced in [18111].

See #32246.

[DrewAPicture]

In 36022:

Docs: Add a missing notation for the $gmt_time parameter in the DocBlock for spawn_cron().

See #32246.

[DrewAPicture]

In 36023:

Docs: Add a missing summary, parameter, and return descriptiosn to the DocBlock for the deprecated function, get_linkrating().

See #32246.

[DrewAPicture]

In 36024:

Docs: Add missing parameter and return notations in the DocBlock for the deprecated _nc() function.

See #32246.

[DrewAPicture]

In 36025:

Docs: Add missing parameter notations and descriptions in the DocBlock for get_link().

See #32246.

[DrewAPicture]

In 36026:

Docs: Add missing parameter and return notations to the DocBlock for the deprecated wp_specialchars() function.

See #32246.

[DrewAPicture]

In 36027:

Docs: Properly mark the $classname parameter as optional.

See #32246.

[DrewAPicture]

In 36028:

Docs: Add missing parameter and return notations in the DocBlock for get_profile().

See #32246.

[DrewAPicture]

In 36030:

Docs: Add missing parameter and return notations to the DocBlock for the deprecated get_usernumposts() function.

See #32246.

[DrewAPicture]

In 36033:

Docs: Add missing notations for the optional $tab_index and $extended parameters in the DocBlock for the deprecated the_editor() function.

See #32246.

[johnbillion]

In 36069:

Docs: Miscellaneous docblock corrections.

See #32246

[DrewAPicture]

In 36070:

Docs: Properly mark the $exclude_zeros parameter in the DocBlock for get_editable_user_ids() as optional.

Also fixes a couple of typos.

See #32246.

[DrewAPicture]

In 36071:

Docs: Add missing @since and properly mark the optional $type parameter as such in the DocBlock for the deprecated get_others_unpublished_posts() function.

Introduced in [5707].

See #32246.

[DrewAPicture]

In 36072:

Docs: Properly mark the optional $redirect, $network_wide, and $silent parameters as such in the DocBlock for activate_plugin().

See #32246.

[johnbillion]

In 36073:

Docs: @see != @since.

See #32246

[johnbillion]

In 36074:

Docs: Miscellaneous docblock code quality tweaks.

See #32246

[johnbillion]

In 36111:

Docs: Correct a funky docblock in funky_javascript_fix().

See #32246

[DrewAPicture]

In 36114:

Docs: Hash notate properties and defaults for the benefit of $args parameter documentation for WP_Customize_Control::__construct().

See #32246.

[rachelbaker]

In 36139:

Docs: Add null to post_id param type, fix syntax, and descriptions in the DocBlock for wp_update_comment_count().

See #32246.

[ocean90]

In 36175:

Docs: Move the hook doc for the the_title filter in Walker_Page::start_el() to directly precede the apply_filters() line.

See #32246.

[dimadin]

We should clarify that media_sideload_image() can return image URL also, and that HTML tag is default value. Example in a patch.

[DrewAPicture]

Replying to dimadin:

We should clarify that media_sideload_image() can return image URL also, and that HTML tag is default value. Example in a patch.

Can you please create a separate ticket and add your patch there?

[johnbillion]

In 36231:

Docs: Correct the parameter docs for various Heartbeat filters and functions.

See #32246

[johnbillion]

In 36232:

Docs: @param fixes for a variety of docblocks.

See #32246

[johnbillion]

In 36248:

Comments: Correct the docblocks for various methods in the comment list table class.

See #32246

[johnbillion]

In 36250:

Docs: Various docblock corrections.

See #32246

[DrewAPicture]

In 36299:

Docs: Adjust formatting for an added-parameter changelog entry in the hook doc for the cron_request filter.

See #32246.

[DrewAPicture]

In 36365:

Docs: Add missing @access tags to DocBlocks for WP class methods and properties.

See #32246.

[DrewAPicture]

In 36391:

Docs: Fix parameter documentation ordering in the hook docs for the register_taxonomy_args filter.

See #32246.

[ocean90]

In 36392:

Docs: Fix indentation in add_filter() example.

See #32246.

[DrewAPicture]

In 36471:

Docs: Add a missing DocBlock for the private _add_themes_utility_last() function.

See #32246.

[DrewAPicture]

In 36472:

Docs: Mark two private functions as such in wp-admin/ajax-actions.php.

See #32246.

[DrewAPicture]

In 36473:

Docs: Add private access notation to the DocBlock for the core _wp_handle_upload() function.

See #32246.

[DrewAPicture]

In 36474:

Docs: Add more complete information to DocBlocks for private core functions _wp_dashboard_control_callback() and _wp_dashboard_recent_comments_row().

See #32246.

[DrewAPicture]

In 36475:

Docs: Reference get_terms() for arguments available in get_categories().

See #32246.

[DrewAPicture]

In 36476:

Docs: Document the $args parameter for get_categories() as a hash notation.

The only specific default for get_categories() is $taxonomy with a value of 'category', all the other arguments are documented separately in get_terms().

See #32246.

[DrewAPicture]

In 36493:

Docs: Add an @access tag and fix a typo in the DocBlock for wpdb::close().

See #34903. See #32246.

[DrewAPicture]

In 36494:

Docs: Slightly simplify the DocBlock summaries for home_url(), get_home_url(), site_url(), and get_site_url().

See #35238. See #32246.

[DrewAPicture]

In 36495:

Docs: Make some minor improvements to inline docs for WP_Site, introduced in [36393].

• Uses third-person singular verbs in method summaries
• Adds an @static tag to the WP_Site::get_instance() DocBlock
• Adjusts return types for WP_Site::get_instance() to the more explicit WP_Site|false

See #32450. See #32246.

[DrewAPicture]

In 36496:

Docs: Update several function DocBlock summaries in wp-includes/nav-menu.php to use third-person singular verbs.

Also removes some unnecessary capitalizations.

See #32246.

[DrewAPicture]

In 36499:

Docs: Add a changelog entry for the introduction of maxlength character limits for the 'author', 'email', and 'url' fields in comment_form().

Introduced in [36272].

See #10377. See #32246.

[DrewAPicture]

In 36500:

Docs: Make a couple of minor improvements to the DocBlock for wp_get_raw_referer(), introduced in [36266].

• Uses a third-person singular verb in the summary
• Makes the return types more specific with string|false vs string|bool.

See #27152. See #32246.

[DrewAPicture]

In 36501:

Docs: Improove the DocBlock summary for wp_signon().

See #32246.

[DrewAPicture]

In 36568:

Docs: Remove a duplicate @static tag from the WP_Customize_Panel->instance_count property DocBlock.

See #32246.

[DrewAPicture]

In 36576:

Docs: Add formatting to a changelog entry in the hook doc for the rest_dispatch_request filter.

See [36534]. See #32246.

[DrewAPicture]

In 36577:

Docs: Add an explanation for the dynamic portion of the {$taxonomy}_term_edit_form_top hook, introduced in [36526].

See #32246.

[rachelbaker]

In 36593:

Docs: Add missing @since and @access tags to get_curies method and filter from r36533

See #34729, #32246.

[DrewAPicture]

In 36687:

Docs: Add an inline @see tag to link up the plugins_loaded hook in the description for the customize_loaded_components filter.

See #32246.

[DrewAPicture]

In 36704:

Posts: Rename the $args parameter in get_post_types_by_support() to $feature for better self-documentation.

See #34010. See #32246.

[DrewAPicture]

In 36705:

Docs: Make a few syntactical improvements to the DocBlock for _wp_get_current_user(), introduced in [36651].

Includes a cross reference from the DocBlock for wp_get_current_user(), which itself is pluggable, but the new internal function is not.

See #19615. See #32246.

[DrewAPicture]

In 36706:

Docs: Standardize DocBlocks for two new WP_Scripts methods, add_inline_script() and print_inline_script(), introduced in [36633].

See #14853. See #32246.

[DrewAPicture]

In 36707:

Docs: Use a third-person singular verb in the DocBlock summary for wp_add_inline_script(), introduced in [36633].

See #14853. See #32246.

[johnbillion]

In 36712:

Docs: Improve the description of the get_object_taxonomies() function. Uncertainty has no place in documentation.

See #32246

[johnbillion]

In 36713:

Docs: Correct the possible return types for WP_Dependencies::query().

See #32246

[DrewAPicture]

In 36723:

Docs: Add a missing @param entry for the $len parameter in the DocBlock for the deprecated generate_random_password() function.

See #32246.

[DrewAPicture]

In 36724:

Docs: Add a missing @param entry for the $user_login parameter in the DocBlock for the deprecated is_site_admin() function.

See #32246.

[DrewAPicture]

In 36725:

Docs: Add some missing @param notations to various DocBlocks in wp-includes/ms-deprecated.php.

See #32246.

[DrewAPicture]

In 36726:

Docs: Standardize summaries for two new internal functions used to handle suffixing trashed posts.

Also adds a notation of private access to each.

See #11863. See #32246.

[DrewAPicture]

In 36727:

Docs: Use the correct variable name for the $post_ID parameter in the DocBlock for wp_add_trashed_suffix_to_post_name_for_trashed_posts().

See #11863. See #32246.

[DrewAPicture]

In 36728:

Docs: Add missing @param and @return notations to the DocBlock for WP_Feed_Cache_Transient::save().

See #32246.

[DrewAPicture]

In 36734:

Docs: Add missing parameter and return descriptions to the DocBlock for WP_Theme::__isset().

See #32246.

[DrewAPicture]

In 36736:

Docs: Add a missing description for the &$themes parameter in the DocBlock for WP_Theme::sort_by_name().

See #32246.

[DrewAPicture]

In 36737:

Docs: Add missing parameter and return notations in the DocBlock for WP_Theme::_name_sort(), a private usort() helper.

See #32246.

[DrewAPicture]

In 36738:

Docs: Add missing parameter and return notations in the DocBlock for WP_Theme::_name_sort_i18n(), a private usort() helper.

See #32246.

[DrewAPicture]

In 36739:

Docs: Fix two typos in return descriptions for WP_Theme private usort() methods.

See #32246.

[DrewAPicture]

In 36745:

Docs: Add a missing summary, @access tag, and parameter documentation to the DocBlock for WP_Customize_Filter_Setting::update().

See #32246.

[DrewAPicture]

In 36748:

Docs: Remove a duplicate parameter notation in the DocBlock for the deprecated the_editor() function.

See #32246.

[DrewAPicture]

In 36753:

Docs: Add missing documentation for the $title parameter in the DocBlock for the deprecated parent_post_rel_link().

See #32246.

[DrewAPicture]

In 36754:

Docs: Add missing documentation for the $wp_admin_bar parameter in the DocBlock for the deprecated wp_admin_bar_dashboard_view_site_menu().

See #32246.

[DrewAPicture]

In 36755:

Docs: Add missing parameter and return documentation to the DocBlock for the deprecated debug_fopen().

Fixes #32246.

[DrewAPicture]

Meh, #32246 is easy to type with one hand (and remember). Might as well just keep using it ;)

[DrewAPicture]

In 36756:

Docs: Add missing parameter documentation to the DocBlock for the deprecated debug_fwrite().

See #32246.

[DrewAPicture]

In 36757:

Docs: Add missing documentation for the $fp parameter to the DocBlock for the deprecated debug_fclose().

See #32246.

[DrewAPicture]

In 36758:

Docs: Add missing documentation for the &$post parameter in the DocBlock for the deprecated _get_post_ancestors().

See #32246.

[DrewAPicture]

In 36759:

Docs: Add missing parameter and return documentation to the DocBlock for the deprecated _search_terms_tidy().

See #32246.

[DrewAPicture]

In 36760:

Docs: Add missing parameter and return descriptions to the DocBlock for the deprecated default_topic_count_text().

See #32246.

[DrewAPicture]

In 36763:

Docs: Improve a variety of DocBlocks in wp-includes/deprecated.php.

See #32246.

[DrewAPicture]

In 36833:

Docs: Improve the DocBlock summary and add a missing initial @since version for WP_Admin_Bar::add_node().

See #32246. See #35986.

[DrewAPicture]

In 36842:

Docs: Improve syntax and correct documentation throughout a variety of methods in WP_Customize_Widgets.

See #32246. See #35986.

[DrewAPicture]

In 36878:

Docs: Add a missing @since version to the DocBlock for wp_add_dashboard_widget().

See #32246.

[jeremyfelt]

In 36893:

Docs: Update the return type for get_current_site()

This is now a WP_Network object.

See #32246.

[DrewAPicture]

In 36940:

Docs: Improve the usefulness of the DocBlock summary for get_edit_term_link().

See #32246.

[DrewAPicture]

In 36942:

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

See #32246.

[johnbillion]

In 36993:

Docs: Improvements and corrections for the $ver parameter of the dependencies API functions.

See #32246

[johnbillion]

In 36994:

Docs: Re-add a @param that went missing in [36993].

See #32246

[johnbillion]

In 36995:

Docs: The $update_result parameter passed to WP_Automatic_Updater::after_core_update() is never a WP_Error. If an error is returned, the error object lives in the result property of the paramter.

See #32246

[ramiy]

Docs: Rewrite the $args parameter in WP_Ajax_Response::add()

[ramiy]

@DrewAPicture Can you review my patch please?

Better docs for: ​WP_Ajax_Response::add()

[DrewAPicture]

@ramiy on class-wp-ajax-response.php.patch​:

• For the $args parameter description, "to override the defaults" is a given. Maybe something like this instead: "Optional. An array or string of XML response arguments."
• The $action argument description should indicate the boolean, i.e. "Whether to use a nonce. Default false."
• In descriptions, we use ID vs id
• For $position, listing out the accepted values and what they mean is helpful, but the description of what the argument represents is missing.
• $supplemental: There should be backticks around <supplemental> in the description

[DrewAPicture]

@ramiy: Also, on the $id and $data arguments, should mention that they also accept a WP_Error object and under what circumstances that might be passed. You can be general, but helpful to have more information than simply that these two args can also accept WP_Error objects. The idea is to explain why :-)

[ramiy]

@DrewAPicture Good feedback, see the attached patch.

[DrewAPicture]

In 37032:

Docs: Document default WP_Ajax_Response::add() arguments as a hash notation.

Adds example output to the DocBlock description based on default argument values.

Props ramiy for the initial patch.
See #32246.

[DrewAPicture]

In 37039:

Docs: Change the 'HTTPS' column header to 'Supports HTTPS' in the markdown providers tables in the hook doc for the oembed_providers filter.

See #32246.

[ramiy]

New docs for WP_Feed_Cache, WP_Feed_Cache_Transient, WP_SimplePie_File, WP_SimplePie_Sanitize_KSES classes, in wp-includes/class-feed.php.

Has patch. Needs review (@DrewAPicture).

[DrewAPicture]

@ramiy: Please create new tickets for specifically-targeted docs fixes. I would say probably a ticket per file would work.

This ticket is sort of a mishmash of stuff we run across now and then, and at 320+ commits/comments and counting, it's not really a great place to upload patches. Loading the page in the browser alone takes a good bit of memory :-)

Let's do separate tickets for targeted fixes by file.

[ramiy]

Done.

See tickets #36295, #36296, #36297, #36298, #36299

[DrewAPicture]

In 37085:

Docs: Add missing quotes around a specifier in a query example in the DocBlock for wpdb::esc_like().

Props madvic.
See #32246.

[DrewAPicture]

In 37086:

Docs: Following [37085], properly indent the markdown-formatted examples in the DocBlock for wpdb::esc_like().

See #32246.

[johnbillion]

In 37209:

Docs: Clarify possible types passed to the themes_api_result filter.

See #32246

[DrewAPicture]

In 37337:

Docs: Standardize on using :: for Class::method() references in WP_Customize_Control` inline docs.

See #32246. See ​#meta1483.

[DrewAPicture]

In 37338:

Docs: Add backtick escaping for two inline code samples in docs.

See #32246.

[DrewAPicture]

In 37342:

Docs: Remove inline @see tags from function, class, and method references in inline docs.

Known functions, classes, and methods are now auto-linked in Code Reference pages following ​#meta1483.

Note: Hook references are still linked via inline @see tags due to the unlikelihood of reliably matching for known hooks based on a RegEx pattern.

See #32246.

[DrewAPicture]

In 37366:

Docs: Remove backticks from the DocBlock summary for WP::$request, added in [37356].

Markdown formatting is not supported in DocBlock summaries, per the inline documentation standards for PHP :-)

See #32246. See #36674.

[SergeyBiryukov]

In 37403:

Docs: Fix typo in a comment in check_and_publish_future_post().

See #32246.

[DrewAPicture]

In 37484:

Docs: Fix some parameter alignment and backtick-escaping in two DocBlocks in wp-admin/includes/media.php.

See #32246.

[DrewAPicture]

In 37545:

Docs: The $context parameter in remove_meta_box() is not optional.

Fixes a copy pasta error introduced in [34952].

Props travisnorthcutt.
See #32246.

[DrewAPicture]

In 37550:

Docs: Fix the hook doc for upgrader_process_complete to notate all values that might be present in the hook_extra array in the various update contexts.

h/t Nextendweb.

See #32246.

[nextendweb]

37550:

@DrewAPicture I'm not sure that the modified documentation describes the structure of that action.
Here is an example action with type => plugin:

<?php
                do_action( 'upgrader_process_complete', $this, array(
                        'action' => 'update',
                        'type' => 'plugin',
                        'bulk' => true,
                        'plugins' => $plugins,
                ) );

In your modified documentation it looks like:

@type string $plugin

but it should be :

@type array $plugins {
  Array of bulk item update data.
...
...
..
}

Same applies for other types, as all of them placed under a different array key.

[DrewAPicture]

Replying to nextendweb:

37550:

@DrewAPicture I'm not sure that the modified documentation describes the structure of that action.
Here is an example action with type => plugin:

<?php
                do_action( 'upgrader_process_complete', $this, array(
                        'action' => 'update',
                        'type' => 'plugin',
                        'bulk' => true,
                        'plugins' => $plugins,
                ) );

In your modified documentation it looks like:

@type string $plugin

but it should be :

@type array $plugins {
  Array of bulk item update data.
...
...
..
}

Same applies for other types, as all of them placed under a different array key.

The documentation was updated based on how core currently implements the hook:

• Language packs (0)
• Plugins (0), (1), (2)
• Themes (0), (1), (2), (3)

Happy to update if you can provide examples in the wild that consistently use a 'plugins' or 'themes' key.

[DrewAPicture]

@nextendweb Actually, I take that back. I see what you're getting at. Let's reopen #36875.

[DrewAPicture]

In 37561:

Docs: Correct DocBlock descriptions for the $before, $after, $link_before, and $link_after arguments for wp_nav_menu().

• $before falls before the link markup starts
• $after falls after the link markup ends
• $link_before falls before the link text
• $link_after falls after the link text

Props wp_smith for the initial patch.

See #32246.

[DrewAPicture]

In 37585:

Docs: Standardizes and improves DocBlock summaries for the __get(), __set(), __isset(), and __unset() magic methods in wpdb.

See #32246.

[DrewAPicture]

In 37586:

Docs: Improve formatting in the DocBlock for sanitize_bookmark_field().

See #32246.

[DrewAPicture]

In 37587:

Docs: Improve documentation for wp_generate_tag_cloud() default arguments by formatting them into in a hash-notation.

See #32246.

[DrewAPicture]

In 37615:

Docs: Improve return descriptions for get_the_category() and get_the_term() to specifically notate that an array of WP_Term objects is returned on success.

See #32246.

[DrewAPicture]

In 37638:

Docs: Reformat several parameter descriptions in Walker_Nav_Menu to directly reference wp_nav_menu() rather than use inline @see tags.

See #32246.

[DrewAPicture]

In 37639:

Docs: Relocate some @see tags and add missing @access tags to method and property DocBlocks in Walker_Nav_Menu.

See #32246.

[DrewAPicture]

In 37671:

Docs: Improve documentation for the $feature parameter in the DocBlock for add_theme_support().

See #32246. See #37067.

[DrewAPicture]

In 37673:

Docs: Improve the DocBlock summary for add_theme_support().

See #32246.

[DrewAPicture]

In 37849:

Docs: Add some missing changelog entries to the DocBlock for add_theme_support().

Part props sirjonathan.
See #32246.

[DrewAPicture]

In 37852:

Docs: Improve the formatting and usefulness of information in the DocBlock for sanitize_text_field().

Also adds missing parameter and return descriptions.

See #32246.

[DrewAPicture]

In 37862:

Docs: Improve the syntax and tensing within the DocBlock for is_home().

See #32246.

[DrewAPicture]

In 37863:

Docs: Add two simple usage examples to the DocBlock for wp_redirect().

See #32246.

[DrewAPicture]

In 37876:

Docs: Make the DocBlock summary for get_option() more explicit and convert to using a third-person singular verb.

See #32246.

[DrewAPicture]

In 37877:

Docs: Add a note to the DocBlock for query_posts() to caution against general usage, including a pointer to the pre_get_posts action.

Also adds missing parameter and return descriptions.

See #32246.

[DrewAPicture]

In 37878:

Docs: Further improve the note of caution within the DocBlock description for query_posts().

See #32246.

[DrewAPicture]

In 37882:

Docs: Improve the usefulness, accuracy, and syntax of the register_post_type() DocBlock summary and description.

See #32246.

[DrewAPicture]

In 37884:

Docs: Improve the $post_type parameter description in the DocBlock for register_post_type().

See #32246.

[DrewAPicture]

In 37885:

Docs: Add a more complete $labels parameter description to the DocBlock for register_post_type().

Directly references get_post_type_labels() for the full list of supported labels.

See #32246.

[DrewAPicture]

In 37886:

Docs: Improve formatting and syntax of the defaullt label docs in the DocBlock for get_post_type_labels().

See #32246.

[DrewAPicture]

In 38018:

Docs: Fix a typo in an inline hook reference in the DocBlock for comment_form().

Props ocean90.
See #32246.

[DrewAPicture]

In 38028:

Docs: Standardize capitalization of Ajax throughout core documentation per the core spelling guide.

Ajax, while considered an acronym for Asynchronous JavaScript and XML, is most commonly capitalized only in the first character.

Part props ocean90.
See #32246.

[DrewAPicture]

In 38029:

Docs: Standardize references to "meta box" or "meta boxes" as two distinct words throughout core documentation per the core spelling guide.

See #32246.

[DrewAPicture]

In 38056:

Docs: Add an initial @since version to wp-includes/feed.php.

The file was introduced in 2.1.0 when it was moved from wp-includes/feed-functions.php in [3862].

See #32246. See #36295.

[DrewAPicture]

In 38106:

Docs: Add a missing DocBlock for the lowercase_octets() function, which is nested within redirect_canonical().

Will be skipped from parsing.

See #32246. See ​#meta942.

[DrewAPicture]

In 38107:

Docs: Use the three-digit, x.x.x-style version in the DocBlock for the nested lowercase_octets() function.

See #32246. See ​#meta942.

[ocean90]

In 38134:

Docs: Change type of WP_Upgrader_Skin::$result to 'string|bool|WP_Error'.

$result can be true too, see Language_Pack_Upgrader::bulk_upgrade().

See #32246.

[johnbillion]

In 38198:

I18N: Correct the documented return types of get_translations_for_domain().

See #32246

[johnbillion]

Closing as fixed as this now has over 300 comments. Follow-up: #37770.