[wp-trac] [WordPress Trac] #42509: Document expected parameters passed to callback functions

[WordPress Trac]

#42509: Document expected parameters passed to callback functions
-------------------------+----------------------------
 Reporter:  johnbillion  |      Owner:
     Type:  enhancement  |     Status:  new
 Priority:  normal       |  Milestone:  Future Release
Component:  General      |    Version:
 Severity:  minor        |   Keywords:  has-patch
  Focuses:  docs         |
-------------------------+----------------------------
 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
 [https://github.com/phpDocumentor/phpDocumentor2/issues/1712 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:

 {{{#!php
 /**
  * @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.

--
Ticket URL: <https://core.trac.wordpress.org/ticket/42509>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform