Make WordPress Core

Changes between Initial Version and Version 4 of Ticket #57299


Ignore:
Timestamp:
12/08/2022 11:31:46 PM (15 months ago)
Author:
johnbillion
Comment:

Replying to jrf:

How would this play together with the 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. 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.

👍

Legend:

Unmodified
Added
Removed
Modified
  • Ticket #57299

    • Property Type changed from defect (bug) to enhancement
  • Ticket #57299 – Description

    initial v4  
    1 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:
     1I'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:
    22
    33{{{#!php