[wp-trac] [WordPress Trac] #57299: Implement array key type notation

[WordPress Trac]

#57299: Implement array key type notation
------------------------------------+-----------------------------
 Reporter:  johnbillion             |      Owner:  (none)
     Type:  defect (bug)            |     Status:  new
 Priority:  normal                  |  Milestone:  Awaiting Review
Component:  General                 |    Version:
 Severity:  normal                  |   Keywords:  2nd-opinion
  Focuses:  docs, coding-standards  |
------------------------------------+-----------------------------
 I'd like to propose that array key type notation is introduced into inline
 documentation where appropriate. This notation uses the syntax `array<key-
 type, value-type>` for arrays, for example a list containing strings is
 documented thus:

 {{{#!php
 /**
  * @param array<int, string> $foo
  */
 }}}

 An associative array of booleans (where the shape is not known) is
 documented thus:

 {{{#!php
 /**
  * @param array<string, bool> $foo
  */
 }}}

 The benefit of this syntax over, for example, `string[]` or
 `array<string>` is it allows the types of the array keys to be specified.
 This allows both lists and associative arrays to be documented more
 completely even when their shape is not known.

 When used in combination with a static analysis tool such as PHPStan this
 allows for greater type safety and more accurate analysis of structures
 such as array access and array iteration. It allows developers looking at
 the documentation to understand the type of the array keys, and thus
 whether an array is a list or associative. That said, I appreciate that
 this syntax is comparatively rare within the WordPress ecosystem and
 therefore can be foreign to developers who've not seen it elsewhere.

 This notation is supported by all of the static analysis tools and code
 editors (either natively or via a PHP add-on) that I could find, including
 VS Code, PHPStorm, Sublime Text, PHPStan, Psalm, and Phan, and it's used
 by countless other frameworks and libraries such as Symfony, Laravel, and
 PHP Parser. It's not a new syntax, it's just new to WordPress core.

 == Benefits

 * Increased awareness of whether an array is a list or an associative
 array for developers reading inline documentation
 * Increased accuracy provided to static analysis tools
 * Increased accuracy in editors and IDEs that either natively support this
 syntax or support the PHP implementation of the language server protocol

 == Concerns

 * Syntax that can be jarring for developers who've not seen it before
 * Not part of a phpDocumentor or PSR-5 PHPDoc standard (although PSR-5 has
 been stalled for 9 years so probably not a concern)

 == Implementation

 Much like the general ongoing improvements to inline docs, this will be a
 gradual process. There won't be a patch or PR that updates all the
 existing `type[]` notation at once.

 Any objections?

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