WordPress.org

Make WordPress Core

Opened 18 months ago

Closed 3 months ago

#42505 closed task (blessed) (fixed)

Docblock improvements for 5.1

Reported by: johnbillion Owned by:
Milestone: 5.1 Priority: normal
Severity: normal Version:
Component: General Keywords:
Focuses: docs Cc:

Description

Previously:

Attachments (8)

42505.diff (0 bytes) - added by birgire 8 months ago.
42505.2.diff (1.8 KB) - added by birgire 8 months ago.
42505.3.diff (603 bytes) - added by birgire 8 months ago.
42505-wp-scripts.diff (2.3 KB) - added by desrosj 8 months ago.
42505-wp-login.diff (4.9 KB) - added by birgire 8 months ago.
42505-class-oembed.diff (10.3 KB) - added by DrewAPicture 6 months ago.
To be merged when Trunk reopens after 5.0
42505-ms-functions.diff (874 bytes) - added by DrewAPicture 6 months ago.
To be merged when Trunk reopens after 5.0
42505-post.diff (675 bytes) - added by DrewAPicture 6 months ago.
To be merged when Trunk reopens after 5.0

Download all attachments as: .zip

Change History (67)

#1 @johnbillion
18 months ago

In 42143:

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

See #42505, #42108

#2 @johnbillion
18 months ago

In 42151:

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

See #42505

#3 @SergeyBiryukov
18 months ago

@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

#4 @johnbillion
17 months ago

In 42216:

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

See #42505

#5 @johnbillion
16 months ago

In 42412:

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

See #42505

#6 @DrewAPicture
15 months ago

In 42660:

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

Props ibachal.
See #42505.

#7 @johnbillion
15 months ago

In 42664:

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

See #42505

#8 @johnbillion
15 months ago

In 42677:

Docs: Update the hook docs for update_bulk_theme_complete_actions.

See #42505

#9 @johnbillion
15 months ago

In 42678:

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

See #42505

#10 @johnbillion
15 months ago

In 42680:

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

See #42505

#11 @johnbillion
15 months ago

In 42681:

Docs: Un-correct an incorrection correction.

See [42680]

See #42505

#12 @SergeyBiryukov
15 months ago

In 42696:

Docs: Fix typo in wp_audio_extensions and wp_video_extensions filter descriptions.

See #42505.

#13 @SergeyBiryukov
14 months ago

In 42712:

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

See #42505.

#14 @SergeyBiryukov
14 months ago

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.

#15 @SergeyBiryukov
14 months ago

In 42748:

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

See #42505, #41452.

#16 @SergeyBiryukov
14 months ago

In 42749:

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

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

#17 @SergeyBiryukov
14 months ago

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.

#18 @SergeyBiryukov
14 months ago

In 42756:

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

See #42505.

#19 @SergeyBiryukov
14 months ago

In 42775:

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

See #42505.

#20 @SergeyBiryukov
14 months ago

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.

#21 @SergeyBiryukov
14 months ago

In 42777:

Docs: Use consistent description for $wp_filesystem global.

See #42505.

#22 @SergeyBiryukov
14 months ago

In 42778:

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

See #42505.

#23 @johnbillion
14 months ago

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

#24 @johnbillion
14 months ago

In 42787:

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

See #42505

#25 @SergeyBiryukov
14 months ago

In 42795:

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

See #42505.

#26 @SergeyBiryukov
14 months ago

In 42821:

Docs: Fix typos in _wp_emoji_list() description.

See #42505.

#27 @SergeyBiryukov
14 months ago

In 42825:

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

See #42505.

#28 @SergeyBiryukov
14 months ago

In 42826:

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

See #42505.

#29 @SergeyBiryukov
13 months ago

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.

#30 @johnbillion
13 months ago

In 42877:

Docs: Correct and improve various inline documentation.

See #42505

#31 @johnbillion
12 months ago

In 43017:

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

Props isabel104

See #42505

#32 @SergeyBiryukov
12 months ago

In 43022:

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

See #42505.

#33 @SergeyBiryukov
12 months ago

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.

#34 @SergeyBiryukov
12 months ago

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.

#35 @johnbillion
12 months ago

In 43043:

Docs: Update the inline docs for is_protected_meta().

See #42505

#36 @johnbillion
12 months ago

In 43177:

Docs: Update and correct various inline documentation.

See #42505, #41756

#37 @johnbillion
11 months ago

In 43258:

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

See #42505

This ticket was mentioned in Slack in #gdpr-compliance by desrosj. View the logs.


11 months ago

#39 @SergeyBiryukov
11 months ago

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.

#40 @SergeyBiryukov
8 months ago

In 43563:

Docs: Correct description for WP_Scripts::$default_version.

See #42505.

@birgire
8 months ago

@birgire
8 months ago

#41 @birgire
8 months ago

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

@birgire
8 months ago

#42 @birgire
8 months ago

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/

#43 @johnbillion
8 months ago

In 43576:

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

Props birgire

See #42505

#44 @desrosj
8 months ago

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().

#45 @johnbillion
8 months ago

In 43582:

Docs: Correct and improve various inline documentation.

See #42505

#46 @johnbillion
8 months ago

In 43583:

Docs: Improve inline documentation for WP_Scripts.

Props desrosj

See #42505

#47 @birgire
8 months ago

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.
Last edited 8 months ago by birgire (previous) (diff)

#48 @johnbillion
7 months ago

In 43642:

Docs: Correct and improve some docblocks.

See #42505

#49 @johnbillion
7 months ago

In 43643:

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

See #42505

#50 @johnbillion
7 months ago

In 43644:

Docs: Improve docblocks within wp-login.php.

Props birgire

See #42505

#51 @SergeyBiryukov
7 months ago

In 43657:

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

See #42505.

#52 @peterwilsoncc
7 months ago

  • Milestone changed from 5.0 to 5.1
  • Summary changed from Docblock improvements for 5.0 to Docblock improvements for 5.1

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

@DrewAPicture
6 months ago

To be merged when Trunk reopens after 5.0

@DrewAPicture
6 months ago

To be merged when Trunk reopens after 5.0

@DrewAPicture
6 months ago

To be merged when Trunk reopens after 5.0

This ticket was mentioned in Slack in #docs by drew. View the logs.


6 months ago

#54 @DrewAPicture
4 months ago

In 44332:

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

Props joyously.
See #42505.

#55 @DrewAPicture
4 months ago

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.

#56 @DrewAPicture
4 months ago

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.

#57 @desrosj
3 months ago

#45210 was marked as a duplicate.

#58 @peterwilsoncc
3 months ago

In 44694:

Docs: Correct documentation for the schedule_event filter.

The filter runs for both recurring and single events.

See #42505.

#59 @pento
3 months ago

  • Resolution set to fixed
  • Status changed from new to closed

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

Note: See TracTickets for help on using tickets.