Adding documentation for WordPress.Arrays.ArrayDeclarationSpacing

[RafaelFunchal]

Related to #1722

[rodrigoprimo]

Thanks for working on adding documentation for WordPress.Arrays.ArrayDeclarationSpacing, @RafaelFunchal! I left inline comments suggesting some improvements.

[rodrigoprimo]

In my opinion, it is slightly better if the multi line examples use one pair of <em> tags per line (here and in the valid example below):

$args = array(
    <em>'post_id' => 22,</em>
    <em>'category' => 1</em>
);

This makes a small difference when generating the HTML version of the documentation (vendor/bin/phpcs --generator=HTML --standard=WordPress --sniffs=WordPress.Arrays.ArrayDeclarationSpacing.

Current version:

Version with the suggested change:

[rodrigoprimo]

I know the sniff error message uses the term associative keys, but I'm inclined to think that just keys is better (and we can also consider updating the sniff error message on a separate PR, if the maintainers agree with the point that I'm raising here). Saying associative keys can be misleading as it might mean to some people that indexed arrays that explicitly declare their keys will not trigger this error when they trigger it. What do you think?

[rodrigoprimo]

I wonder if we should include an example of an associative array that triggers this error to make it explicitly that this one is not only about indexed arrays without declared keys?

The error above is only triggered for single-line arrays with declared keys.

[rodrigoprimo]

Also, should we include in the invalid phrase that this only happens on a multi-line array? Maybe something like: Invalid: More than one item per line in a multi-line array.

[rodrigoprimo]

I believe that key/value pair is more commonly used than pair of key and value.

[rodrigoprimo]

Aside from the issue the sniff is about, please check that the code in each code sample follows the WP Coding Standards. I believe this code example is missing a trailing comma after the last array item, and the alignment of the first double arrow is incorrect.