#48397 closed defect (bug) (fixed)
PHPDoc correction for wptexturize() in wp-includes/formatting.php
Reported by: | atachibana | Owned by: | SergeyBiryukov |
---|---|---|---|
Milestone: | 5.4 | Priority: | normal |
Severity: | minor | Version: | |
Component: | Formatting | Keywords: | has-patch |
Focuses: | docs | Cc: |
Description
Enhanced missing information of Codex for add_help_tab() in wp-admin/includes/class-wp-screen.php:
- Function description
- since 4.0 information
Other missing information in Notes section were added to Code Reference as 'More Information'.
Codex: https://codex.wordpress.org/Function_Reference/wptexturize
Code Reference: https://developer.wordpress.org/reference/functions/wptexturize/
This is the action of inline docs and Codex migration initiatives.
Index: formatting.php =================================================================== --- formatting.php (revision 46568) +++ formatting.php (working copy) @@ -10,6 +10,8 @@ /** * Replaces common plain text characters into formatted entities * + * This returns given text with transformations of quotes to smart quotes, + * apostrophes, dashes, ellipses, the trademark symbol, and the multiplication symbol. * As an example, * * 'cause today's effort makes it worth tomorrow's "holiday" ... @@ -23,6 +25,7 @@ * Do not use this function before the {@see 'init'} action hook; everything will break. * * @since 0.71 + * @since 4.0 Revised to improve performance and to resolve many bugs. Added the run_wptexturize filter to allow a theme or plugin to permanently disable this feature. * * @global array $wp_cockneyreplace Array of formatted entities for certain common phrases * @global array $shortcode_tags
Attachments (1)
Change History (8)
#3
@
5 years ago
- Component changed from General to Formatting
- Milestone changed from Awaiting Review to 5.4
- Owner set to SergeyBiryukov
- Status changed from new to reviewing
#4
in reply to:
↑ 2
@
5 years ago
Replying to johnbillion:
For each major release of WordPress we use a single tracking ticket for small inline documentation fixes such as this, so as to avoid a large number of documentation-only tickets on Trac. For 5.4 it's ticket #48303.
FWIW, I find it easier to handle well-contained tickets like this separately than reviewing a lot of different changes on a single ticket, but yeah, either way should work.
#5
@
5 years ago
Thanks for the patch!
Just noting that, per the documentation standards, @since
tags are generally added for significant changes like:
- Adding new arguments or parameters
- Required arguments becoming optional
- Changing default/expected behaviors
- Functions or methods becoming wrappers for new APIs
Of the two sentences added here, neither quite seem to fit:
- Revised to improve performance and to resolve many bugs.
- Added the
run_wptexturize
filter to allow a theme or plugin to permanently disable this feature.
The former is an internal implementation detail that does not change the function signature and does not provide any information on the behavior changes, the latter seems redundant and just duplicates the existing filter documentation. New filters or actions generally have their own documentation and are not added to @since
tags.
#7
@
5 years ago
@johnbillion
I didn't know about the #48303.
I modified the inline documentation guide of Docs Team Handbook to follow your instruction.
https://make.wordpress.org/docs/handbook/code-reference/inline-documentation/
@SergeyBiryukov
Thank you for your always kindly guides.
I'll continue to include as much as details of the bug report even in the Comment area.
@atachibana Thanks for the tickets! For each major release of WordPress we use a single tracking ticket for small inline documentation fixes such as this, so as to avoid a large number of documentation-only tickets on Trac. For 5.4 it's ticket #48303. Feel free to leave your comments on that ticket for any further improvements you identify.