[wp-trac] [WordPress Trac] #48397: PHPDoc correction for wptexturize() in wp-includes/formatting.php

[WordPress Trac]

#48397: PHPDoc correction for wptexturize() in wp-includes/formatting.php
--------------------------+-----------------------------
 Reporter:  atachibana    |       Owner:  SergeyBiryukov
     Type:  defect (bug)  |      Status:  reviewing
 Priority:  normal        |   Milestone:  5.4
Component:  Formatting    |     Version:
 Severity:  minor         |  Resolution:
 Keywords:  has-patch     |     Focuses:  docs
--------------------------+-----------------------------

Comment (by SergeyBiryukov):

 Thanks for the patch!

 Just noting that, per the [https://make.wordpress.org/core/handbook/best-
 practices/inline-documentation-standards/php/#since-section-changelogs
 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.

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/48397#comment:5>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform