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

[WordPress Trac]

#57299: Implement array key type notation
-------------------------+-------------------------------------
 Reporter:  johnbillion  |       Owner:  (none)
     Type:  enhancement  |      Status:  new
 Priority:  normal       |   Milestone:  Awaiting Review
Component:  General      |     Version:
 Severity:  normal       |  Resolution:
 Keywords:  2nd-opinion  |     Focuses:  docs, coding-standards
-------------------------+-------------------------------------

Old description:

> 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?

New description:

 I'd like to propose that array key type notation is introduced into PHP
 docblocks 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?

--

Comment (by johnbillion):

 Replying to [comment:3 jrf]:
 > How would this play together with the [https://developer.wordpress.org
 /coding-standards/inline-documentation-standards/php/#1-1-parameters-that-
 are-arrays WP array annotations used for parameters/hooks] ?

 I think they can go hand-in-hand as they partially do at the moment with
 the existing `type[]` syntax. [https://github.com/WordPress/wordpress-
 develop/blob/1f0af5b5ae1aa3587dd4f25db4056c10669b8d2d/src/wp-includes
 /class-wp-date-query.php#L578-L583 Given this example], this is the
 before:

 {{{
 * @return string[] {
 *     Array containing JOIN and WHERE SQL clauses to append to the main
 query.
 *
 *     @type string $join  SQL fragment to append to the main JOIN clause.
 *     @type string $where SQL fragment to append to the main WHERE clause.
 * }
 }}}

 And this is the after:

 {{{
 * @return array<string, string> {
 *     Array containing JOIN and WHERE SQL clauses to append to the main
 query.
 *
 *     @type string $join  SQL fragment to append to the main JOIN clause.
 *     @type string $where SQL fragment to append to the main WHERE clause.
 * }
 }}}

 The `array<key-type, value-type>` syntax allows for nesting. Whether or
 not that's necessary or appropriate for multi-dimensional arrays can be
 made on a case by case basis.

 > How would one go about documenting arrays with `mixed` types, i.e.
 different types for different/specific associative array keys ?

 `mixed` is a valid type. There's currently three instances of `mixed[]` in
 core. These can either remain as `mixed[]` if the key types are unknown,
 or converted to `array<int, mixed>`, `array<string, mixed>`, or
 `array<int|string, mixed>` as appropriate to be more explicit.

 Alternatively, union types are valid in this notation just as they are
 without it, although I am not sure if there's any instances of this in
 core currently, for example `(string|int)[]` could become `array<int,
 string|int>` if it's a list.

 > Would this also apply to return and hook types ?

 IMO it should apply to `@param`, `@return`, and `@var` tags, which
 therefore includes hook documentation, and also `@type` tags inside the
 WP-specific object hash notation. I will need to check whether the WP-
 Parser library used to generate the documentation for
 developer.wordpress.org needs any updates too.

 > Also missing any mention of PHP_CodeSniffer in your list of tools, while
 that is the typical tooling used to check docs styling in CI in the WP
 world.

 I did include PHPCS in my list originally, but then it crossed my mind
 that I wasn't aware of explicit support for this notation in PHPCS so I
 left it out. If it is supported then great!

 > P.S.: this is not about inline documentation, but about docblocks. You
 may want to change that in the description.

 👍

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