[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