Docblock improvements for 5.1

[johnbillion]

Previously:

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

[johnbillion]

In 42143:

Docs: Improve inline docs for the wp_redirect() and wp_safe_redirect() functions.

See #42505, #42108

[johnbillion]

In 42151:

Docs: Correct parameter type documentation for various __call() methods.

See #42505

[SergeyBiryukov]

@afercia in #42530:

• ...seems to me all the new functions introduced in [41630] miss a @since notation in their docblocks.
• Additional note about documentation standards: many multiline inline comments introduced in [41630] use a double asterisk, e.g.:

  /**
   * If the selection is on a shortcode with Live View, TinyMCE creates a bogus markup,
   * which we have to account for.
   */
  

• Note: one more coding standard that isn't met across [41630]: ​Declaring Variables With var
  • Each function should begin with a single comma-delimited var statement that declares any local variables necessary

[johnbillion]

In 42216:

Cron API: Improvements to docblocks for the event scheduling functions.

See #42505

[johnbillion]

In 42412:

Docs: Improve the function and parameter descriptions for do_meta_boxes().

See #42505

[DrewAPicture]

In 42660:

Docs: Fix a typo in the DocBlock description for get_bloginfo() illustrating the URL structure for RDF feeds.

Props ibachal.
See #42505.

[johnbillion]

In 42664:

Docs: Copy a helpful inline doc into the function header for visibility.

See #42505

[johnbillion]

In 42677:

Docs: Update the hook docs for update_bulk_theme_complete_actions.

See #42505

[johnbillion]

In 42678:

Docs: Add missing code formatting to various @since entries.

See #42505

[johnbillion]

In 42680:

Docs: Correct some secondary documentation for the https_local_ssl_verify and https_ssl_verify filters.

See #42505

[johnbillion]

In 42681:

Docs: Un-correct an incorrection correction.

See [42680]

See #42505

[SergeyBiryukov]

In 42696:

Docs: Fix typo in wp_audio_extensions and wp_video_extensions filter descriptions.

See #42505.

[SergeyBiryukov]

In 42712:

Docs: Move inline comments in wp_kses_split2() before the blocks they apply to.

See #42505.

[SergeyBiryukov]

In 42720:

Docs: Correct documentation for Heartbeat filters.

$response parameter is documented as an array or object, but only array is actually supported.

See #42777, #42505.

[SergeyBiryukov]

In 42748:

Docs: Remove @access notation from WP_Taxonomy::$meta_box_sanitize_cb.

See #42505, #41452.

[SergeyBiryukov]

In 42749:

Twenty Fourteen: Remove redundant @access and @static notations from classes.

Props birgire.
See #41452, #42803, #42505.

[SergeyBiryukov]

In 42750:

Docs: Remove duplicated DocBlock for http_response hook in WP_Http::_dispatch_request().

The filter is already documented in WP_Http::request().

See #42505.

[SergeyBiryukov]

In 42756:

Docs: Add missing @since entries for functions in wp-admin/image-edit.php.

See #42505.

[SergeyBiryukov]

In 42775:

Docs: Clarify download_url() return value, improve DocBlock formatting.

See #42505.

[SergeyBiryukov]

In 42776:

Docs: Clarify return values and improve DocBlock formatting for verify_file_md5(), unzip_file(), _unzip_file_ziparchive(), _unzip_file_pclzip(), copy_dir(), WP_Filesystem().

See #42505.

[SergeyBiryukov]

In 42777:

Docs: Use consistent description for $wp_filesystem global.

See #42505.

[SergeyBiryukov]

In 42778:

Docs: Expand delete_theme() return value, fix typo in delete_plugins() return value.

See #42505.

[johnbillion]

In 42786:

Upgrade/Install: Fix the format of the upgrader_process_complete actions after [42343].

More info: ​https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards/issues/1323

See #41057, #42505

[johnbillion]

In 42787:

Docs: Standardise and correct documentation relating to parameters which accept plugin names.

See #42505

[SergeyBiryukov]

In 42795:

Docs: Document globals in wp-admin/revision.php as @global instead of @param.

See #42505.

[SergeyBiryukov]

In 42821:

Docs: Fix typos in _wp_emoji_list() description.

See #42505.

[SergeyBiryukov]

In 42825:

Docs: Add missing brace in auto_update_{$type} filter DocBlock.

See #42505.

[SergeyBiryukov]

In 42826:

Docs: Fix typo in a comment in WP_Community_Events::trim_events().

See #42505.

[SergeyBiryukov]

In 42873:

Docs: Correct method reference in a comment for Bulk_Plugin_Upgrader_Skin::$plugin_info.

See [42677] for Bulk_Theme_Upgrader_Skin::$theme_info.

See #42505.

[johnbillion]

In 42877:

Docs: Correct and improve various inline documentation.

See #42505

[johnbillion]

In 43017:

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

Props isabel104

See #42505

[SergeyBiryukov]

In 43022:

Docs: Add missing verb in is_admin(), is_blog_admin(), is_network_admin(), is_user_admin() descriptions.

See #42505.

[SergeyBiryukov]

In 43023:

Docs: Remove backtick-escaping around a core function in the hook docs for the comment_form_submit_button filter.

This allows the function to be auto-linked in the Developer Reference. See [32037] for comment_form_submit_field.

See #42505, #31888.

[SergeyBiryukov]

In 43024:

Docs: Remove backtick-escaping around a core function in the hook docs for the pre_prepare_themes_for_js filter.

This allows the function to be auto-linked in the Developer Reference. Added in [42877].

See #42505.

[johnbillion]

In 43043:

Docs: Update the inline docs for is_protected_meta().

See #42505

[johnbillion]

In 43177:

Docs: Update and correct various inline documentation.

See #42505, #41756

[johnbillion]

In 43258:

Docs: Add missing HTTP methods to the list of those supported.

See #42505

[SergeyBiryukov]

In 43307:

Docs: Escape the <!--nextpage--> page tag in wp_link_pages() and get_the_content() description for proper display in Developer Reference.

Props grapplerulrich.
See #42505.

[SergeyBiryukov]

In 43563:

Docs: Correct description for WP_Scripts::$default_version.

See #42505.

[birgire]

42505.2.diff​ fixes typo and variable formatting in the inline description of wp_add_inline_script() and wp_add_inline_style().

[birgire]

42505.3.diff​ removes an extra } from the inline description for wp_page_menu(). I wonder if it was meant to be {@see wp_list_pages()}, but it seems to be unnecessary as the link is already generated on:

​https://developer.wordpress.org/reference/functions/wp_page_menu/

[johnbillion]

In 43576:

Docs: Remove an erroneous closing brace from the description of wp_list_pages().

Props birgire

See #42505

[desrosj]

In 42505-wp-scripts.diff​:

• Add missing @param and @return descriptions to WP_Scripts->localize().
• Add missing periods at the end of inline comments.
• Fix parameter alignment for WP_Scripts->add_inline_script() and WP_Scripts->set_group().

[johnbillion]

In 43582:

Docs: Correct and improve various inline documentation.

See #42505

[johnbillion]

In 43583:

Docs: Improve inline documentation for WP_Scripts.

Props desrosj

See #42505

[birgire]

The patch in 42505-wp-login.diff​ contains suggestions for wp-login.php that:

• Adds missing @since annotation for the action:
  • user_request_action_confirmed
• Adds missing @since annotation for the functions:
  • wp_shake_js(),
  • wp_login_viewport_meta(),
  • retrieve_password(),
  • login_header(),
  • login_footer().
• Adds missing description for the functions:
  • wp_shake_js(),
  • wp_login_viewport_meta().
• Adds missing full-stops for inline comments.
• Capitalizes inline comments.
• Capitalizes https and ssl in inline comments.

[johnbillion]

In 43642:

Docs: Correct and improve some docblocks.

See #42505

[johnbillion]

In 43643:

Docs: Correct and improve docblocks for user session management functionality.

See #42505

[johnbillion]

In 43644:

Docs: Improve docblocks within wp-login.php.

Props birgire

See #42505

[SergeyBiryukov]

In 43657:

Docs: Add a line break to wp_is_uuid() DocBlock for better readability.

See #42505.

[peterwilsoncc]

Renaming and moving to the 5.1 milestone due to the WordPress 5.0 focus on the new
editor (Gutenberg).

[DrewAPicture]

To be merged when Trunk reopens after 5.0

[DrewAPicture]

To be merged when Trunk reopens after 5.0

[DrewAPicture]

To be merged when Trunk reopens after 5.0

[DrewAPicture]

In 44332:

Docs: Fix an @see reference to use the correct class name in the wp_script_add_data() DocBlock.

Props joyously.
See #42505.

[DrewAPicture]

In 44333:

Docs: Remove erroneous pipe character usage in the oembed_providers filter DocBlock.

Avoids markdown table display errors when parsed and displayed in the Code Reference.

See #42505.

[DrewAPicture]

In 44334:

Docs: Add backtick escaping around a variable name in the DocBlock for update_post_meta().

Also adds a note to the description explaining that it can be used in place of add_post_meta().

See #42505.

[desrosj]

#45210 was marked as a duplicate.

[peterwilsoncc]

In 44694:

Docs: Correct documentation for the schedule_event filter.

The filter runs for both recurring and single events.

See #42505.

[pento]

RC1 is arriving soon, so I'm closing this ticket out.

[SergeyBiryukov]

#41367 was marked as a duplicate.