Opened 6 years ago
Closed 11 months ago
#42509 closed enhancement (maybelater)
Document expected parameters passed to callback functions
Reported by: |
|
Owned by: | |
---|---|---|---|
Milestone: | Priority: | normal | |
Severity: | minor | Version: | |
Component: | General | Keywords: | needs-patch |
Focuses: | docs | Cc: |
Description
Around eighty function parameters in WordPress accept a callback function (documented with the callable
type), but none of these parameters document the expected parameters that get passed to the callback function.
phpDocumentor doesn't have a syntax for this. It's currently being discussed but isn't a high priority.
I think it's safe to say that the following syntax is the most sensible and the most similar to the existing associative array parameter notation:
/**
* @param callable $callback {
* The callback function description.
*
* @type string $one A string.
* @type int $two An integer.
* @return string A nicely formatted string.
* }
*/
function foo( $callback ) {
echo call_user_func( $callback, 'one', 2 );
}
The @return
notation for the callback could also be specified, but we'd need to check whether it interferes with the docs parser and fix it if so.
Let's start with a couple of instances and once we're happy with the syntax, go from there.
Change History (4)
Note: See
TracTickets for help on using
tickets.
It's worth noting that in the (very old) PSR-5 draft, a syntax for
@method
notation was proposed which effectively documents callable parameters, but it's pretty nasty, and PSR-5 hasn't had any traction in several years. See https://github.com/phpDocumentor/fig-standards/blob/master/proposed/phpdoc.md#711-method