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

WordPress Trac noreply at wordpress.org
Tue Aug 27 16:57:32 UTC 2024


#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 flixos90):

 Replying to [comment:3 joemcgill]:
 > The argument against is that the function technically does support
 string values for those parameters for backwards compatibility.

 While that's true, I think it's better to focus documentation on how the
 functions should be used. Explaining backward compatibility in parameter
 documentation is unnecessary detail to someone that intends to use the
 function and can lead to confusion. IMO backward compatibility is about
 avoiding breakage in the functionality, less about documentation. For
 instance, if we were now type-hinting `bool` in the actual parameters,
 that would be a functional change, but changing only the documentation
 won't cause breakage. If anything, it will lead to certain linting tools
 (e.g. PHPStan) complaining, which I think is something that we would want.

 > Do you know if there other places where we intentionally limit the param
 values in docs to exclude values that are only supported for backwards
 compatibility purposes?

 I'm not sure off the top of my head. But I'm also not sure there are
 places where we explicitly document them, unless they're entire parameters
 that got (soft or hard) deprecated.

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


More information about the wp-trac mailing list