Make WordPress Core

Opened 6 years ago

Closed 21 months ago

#42509 closed enhancement (maybelater)

Document expected parameters passed to callback functions

Reported by: johnbillion's profile johnbillion 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)

#1 @johnbillion
6 years ago

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

This ticket was mentioned in Slack in #core by markparnell. View the logs.


3 years ago

#3 @markparnell
3 years ago

  • Keywords needs-patch added; has-patch removed

#4 @johnbillion
21 months ago

  • Milestone Future Release deleted
  • Resolution set to maybelater
  • Status changed from new to closed
Note: See TracTickets for help on using tickets.