`SlevomatCodingStandard.Commenting.DocCommentSpacing.IncorrectOrderOfAnnotationsGroup` Doesn't respect array shape comments

[marekdedic]

Hi, I am using the WordPress style documentation for array fields that go like so:

/**
 * A list of all currently overriden options.
 *
 * @var array<int|string> $overriden {
 *     All the fields are optional.
 *
 *     @type int    $grid_height The height of a row in the image grid.
 *     @type int    $grid_spacing Item spacing in the image grid.
 *     @type string $dir_title_size Directory title size, including CSS units.
 *     @type string $dir_counts Whether to show directory item counts. Accepts `true`, `false`.
 *     @type string $dir_ordering_by What to order images by. Accepts `name`, `time`.
 *     @type string $dir_ordering_order Whether to order images in ascending or descending order. Accepts `ascending`, `descending`.
 * }
 */
private $overriden;

However, it seems that 8.13 cannot read this - specifically it complains about order of annotation groups and the autofix has a tendency to move things from inside the {} outside - breaking the type annotation in the process...

Full issue here: https://github.com/skaut/skaut-google-drive-gallery/pull/2044

[kukulich]

Not sure if it's possible to support this. It's not standard doccomment.

[marekdedic]

Yeah, it's not. However, the standards regarding phpDoc are kind of lacking, for example the array<int|string> syntax is AFAIK also not standardized, yet it is used by many tools....

I'd argue that WordPress is big enough to pay attention to what is used in it (and the plugins and themes follow that), but that's a decision you have to make :)

[ondrejmirtes]

I'd argue that Wordpress should switch to array shapes currently understood by Slevomat CS, PHPStan, Psalm, and PhpStorm: https://phpstan.org/writing-php-code/phpdoc-types#array-shapes

[marekdedic]

And I'd agree with you. But I'm not a member of the WordPress core team, just a plugin developer trying to make this all work together :shrug:

[marekdedic]

https://core.trac.wordpress.org/ticket/57299