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.
👍