Context Navigation

← Previous Ticket
Next Ticket →

#42505 closed task (blessed) (fixed)

Docblock improvements for 5.1

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

Description

Previously:

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

Attachments (8)

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

Download all attachments as: .zip

Change History (68)

#1 @johnbillion
9 years ago

In 42143:

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

See #42505, #42108

#2 @johnbillion
9 years ago

In 42151:

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

See #42505

#3 @SergeyBiryukov
9 years 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
9 years ago

In 42216:

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

See #42505

#5 @johnbillion
9 years ago

In 42412:

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

See #42505

#6 @DrewAPicture
8 years 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
8 years ago

In 42664:

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

See #42505

#8 @johnbillion
8 years ago

In 42677:

Docs: Update the hook docs for update_bulk_theme_complete_actions.

See #42505

#9 @johnbillion
8 years ago

In 42678:

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

See #42505

#10 @johnbillion
8 years ago

In 42680:

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

See #42505

#11 @johnbillion
8 years ago

In 42681:

Docs: Un-correct an incorrection correction.

See [42680]

See #42505

#12 @SergeyBiryukov
8 years ago

In 42696:

Docs: Fix typo in wp_audio_extensions and wp_video_extensions filter descriptions.

See #42505.

#13 @SergeyBiryukov
8 years ago

In 42712:

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

See #42505.

#14 @SergeyBiryukov
8 years 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
8 years ago

In 42748:

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

See #42505, #41452.

#16 @SergeyBiryukov
8 years ago

In 42749:

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

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

#17 @SergeyBiryukov
8 years 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
8 years ago

In 42756:

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

See #42505.

#19 @SergeyBiryukov
8 years ago

In 42775:

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

See #42505.

#20 @SergeyBiryukov
8 years 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
8 years ago

In 42777:

Docs: Use consistent description for $wp_filesystem global.

See #42505.

#22 @SergeyBiryukov
8 years ago

In 42778:

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

See #42505.

#23 @johnbillion
8 years 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
8 years ago

In 42787:

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

See #42505

#25 @SergeyBiryukov
8 years ago

In 42795:

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

See #42505.

#26 @SergeyBiryukov
8 years ago

In 42821:

Docs: Fix typos in _wp_emoji_list() description.

See #42505.

#27 @SergeyBiryukov
8 years ago

In 42825:

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

See #42505.

#28 @SergeyBiryukov
8 years ago

In 42826:

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

See #42505.

#29 @SergeyBiryukov
8 years 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
8 years ago

In 42877:

Docs: Correct and improve various inline documentation.

See #42505

#31 @johnbillion
8 years ago

In 43017:

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

Props isabel104

See #42505

#32 @SergeyBiryukov
8 years ago

In 43022:

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

See #42505.

#33 @SergeyBiryukov
8 years 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
8 years 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
8 years ago

In 43043:

Docs: Update the inline docs for is_protected_meta().

See #42505

#36 @johnbillion
8 years ago

In 43177:

Docs: Update and correct various inline documentation.

See #42505, #41756

#37 @johnbillion
8 years 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.

8 years ago

#39 @SergeyBiryukov
8 years ago

In 43307:

Docs: Escape the  page tag in wp_link_pages() and get_the_content() description for proper display in Developer Reference.

Props grapplerulrich.
See #42505.

#40 @SergeyBiryukov
8 years ago

In 43563:

Docs: Correct description for WP_Scripts::$default_version.

See #42505.

@birgire
8 years ago

Attachment 42505.diff added

@birgire
8 years ago

Attachment 42505.2.diff added

#41 @birgire
8 years 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 years ago

Attachment 42505.3.diff added

#42 @birgire
8 years 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 years ago

In 43576:

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

Props birgire

See #42505

@desrosj
8 years ago

Attachment 42505-wp-scripts.diff added

#44 @desrosj
8 years 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 years ago

In 43582:

Docs: Correct and improve various inline documentation.

See #42505

#46 @johnbillion
8 years ago

In 43583:

Docs: Improve inline documentation for WP_Scripts.

Props desrosj

See #42505

#47 @birgire
8 years 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_footer(),
- 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.