PHPDoc correction for wptexturize() in wp-includes/formatting.php

[atachibana]

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

[johnbillion]

@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.

[SergeyBiryukov]

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.

[SergeyBiryukov]

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.

[SergeyBiryukov]

In 46592:

Docs: Improve documentation for wptexturize().

Props atachibana.
Fixes #48397.

[atachibana]

@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.