[wp-trac] [WordPress Trac] #61929: Update documentation for remaining autoload functions to only include `true|false` as parameter values

[WordPress Trac]

#61929: Update documentation for remaining autoload functions to only include
`true|false` as parameter values
--------------------------------+--------------------------------
 Reporter:  flixos90            |       Owner:  flixos90
     Type:  defect (bug)        |      Status:  assigned
 Priority:  normal              |   Milestone:  6.7
Component:  Options, Meta APIs  |     Version:
 Severity:  normal              |  Resolution:
 Keywords:  has-patch           |     Focuses:  docs, performance
--------------------------------+--------------------------------

Comment (by jrf):

 Replying to [comment:9 flixos90]:
 > Replying to [comment:7 jrf]:
 > > Might it be an idea to official mark those old values as deprecated ?
 Either soft deprecated (documentation only) or hard deprecated and flagged
 via a call to the
 [https://developer.wordpress.org/reference/functions/_deprecated_argument/
 `_deprecated_argument()` function] ?
 >
 > Could you clarify what you think soft deprecation could look like in
 this context? The documentation already states that these values are only
 supported for backward compatibility.

 Happy to. Soft deprecation is a deprecation in documentation only, but
 does make the deprecation explicit (currently it is implied).

 In practice, this would mean something along the lines of:
 * Adding a `@since` tag (or maybe even a `@deprecated` tag, this would
 need to be checked against prior art, but I seem to remember it should be
 `@since`) stating that passing 'yes|no' to the `$autoload` parameter is
 deprecated.
 * Probably updating the phrasing in the parameter description from ''"For
 backward compatibility 'yes' and 'no' are also accepted. <snip> ... it is
 recommended to autoload them, by using 'yes'|true."'' to something along
 the lines of ''"For backward compatibility, 'yes' and 'no' are still
 accepted, though using these values is deprecated. <snip> ... it is
 recommended to autoload them, by using `true`."'' (note the removal of the
 deprecated value from the recommendation)

 >
 > Regarding hard deprecation, I don't think we should do that at this
 point. From a code perspective it would make sense, but historically we
 haven't hard-deprecated things when they're still very commonly used in
 the ecosystem and are easy to maintain (both of which applies here).

 Fair point. Maybe a "Future release" ticket should be opened as a reminder
 to do this in WP 7.0 (or later) ?

 The exact "when" could possibly be determined based on stats from the
 plugin directory. "If more than 50% of the relevant function calls in
 plugins use the `true|false|null` values, hard deprecate the soft
 deprecated values" (or something like that).

 The sniff which is being worked on, could include "metrics" (a stats
 feature) which would make it straight forward to get such statistics about
 the values being passed to `$autoload` using PHPCS with the
 `--report=info` flag.

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