[wp-trac] [WordPress Trac] #37402: Standardise documentation for variadic functions

[WordPress Trac]

#37402: Standardise documentation for variadic functions
------------------------------------------------+--------------------------
 Reporter:  johnbillion                         |       Owner:
     Type:  task (blessed)                      |      Status:  new
 Priority:  normal                              |   Milestone:  Future
Component:  General                             |  Release
 Severity:  minor                               |     Version:
 Keywords:  needs-patch needs-docs 2nd-opinion  |  Resolution:
                                                |     Focuses:  docs
------------------------------------------------+--------------------------

Comment (by johnbillion):

 PHP_CodeSniffer, phpDocumentor, and PhpStorm have all adopted this format
 for documenting variadic parameters:

 {{{
 @param type ...$name Description
 }}}

 This format matches the actual PHP 5.6+ syntax for variadic parameters. if
 PSR-5 ever arrives, it will also use this format.

 Refs:
 * https://github.com/squizlabs/PHP_CodeSniffer/issues/841
 * https://github.com/phpDocumentor/fig-standards/issues/121
 * http://php.net/manual/en/functions.arguments.php#functions.variable-arg-
 list
 * https://github.com/phpDocumentor/phpDocumentor2/issues/629

 WordPress core currently mostly uses the older syntax which was born from
 the PHP RFCs for variadic parameters:

 {{{
 @param type $name,... Description
 }}}

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