[wp-trac] [WordPress Trac] #41756: Document arrays of a known type as such

[WordPress Trac]

#41756: Document arrays of a known type as such
-------------------------+---------------------------------
 Reporter:  johnbillion  |      Owner:
     Type:  enhancement  |     Status:  new
 Priority:  low          |  Milestone:  Awaiting Review
Component:  General      |    Version:
 Severity:  normal       |   Keywords:  ongoing 2nd-opinion
  Focuses:  docs         |
-------------------------+---------------------------------
 A parameter that accepts an array (or avariable that contains an array)
 usually has its type documented with the `array` keyword:

 {{{
 @param array $args Arguments.
 }}}

 phpDocumentor and IDEs such as PhpStorm support a secondary notation for
 arrays which specifies the type of the elements that the array contains.
 Example:

 {{{
 @param string[] $args Arguments.
 }}}

 This form of notation makes it clearer which type the application expects
 in an array's elements. WordPress core should switch to documenting arrays
 of known types to this format.

 Ref: https://docs.phpdoc.org/references/phpdoc/types.html#arrays

 ----

 Addendum: phpDocumentor also supports documenting arrays containing mixed
 types with the following syntax, but this could get messy:

 {{{
 @param (int|string)[] $args Arguments.
 }}}

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