Multiline array documentation phpdoc support

[simPod]

Multiline array structure documentation is currently not possible but seems handy for wide arrays.

<?php

declare(strict_types=1);

final class A
{
    /**
     * @param array{
     *   a: string,
     *   b: int
     *   } $result
     */
    public function aaa(array $result) : void
    {
    }
}

PHPDoc tag @param has invalid value (array{
a: string,
b: int): Unexpected token "\n *", expected TOKEN_IDENTIFIER at offset 24 |

https://phpstan.org/r/7e3b0b6d-e264-4f31-b70c-1beefac23a8b

Not sure whether phpstan thing though.

[ondrejmirtes]

@JanTvrdik, who is the author of the brilliant phpdoc-parser, does not find this feasible.

[muglug]

I'm not sure why it's not feasible — Psalm does it without incident. As Ondrej has pointed out, it's less efficient to use arrays instead of objects, but that's a separate issue.

[simPod]

@muglug yup, I'm receiving array from JSON RPC API and converting it to object, but I was thinking documenting its shape would be good idea 🤔

The problem with single line shape documentation is that it fits to 2 4K screens minimum and new issues arise (like IDE tries to wrap it to multiple lines when autoformatting, violation of max line length sniff etc.)

@ondrejmirtes maybe we can move this issue to phpdoc-parser repo, did not know it existed at the time of creating this.

[ondrejmirtes]

Implemented: phpstan/phpdoc-parser#33