Multiline return fails to parse

[Majkl578]

Having this phpDoc:

    /**
     * Parses and builds AST for the given Query.
     *
     * @return \Doctrine\ORM\Query\AST\SelectStatement |
     *         \Doctrine\ORM\Query\AST\UpdateStatement |
     *         \Doctrine\ORM\Query\AST\DeleteStatement
     */

PHPStan 0.9.2 errors with:

  234    PHPDoc tag @return has invalid value (\Doctrine\ORM\Query\AST\SelectStatement |): Unexpected token "\n     *", expected TOKEN_IDENTIFIER at offset 117

This is currently used in Doctrine: https://github.com/doctrine/doctrine2/blob/2de6c807c8617b888bbb9da8b0908648432b3673/lib/Doctrine/ORM/Query/Parser.php#L227

Is this by design, bug or simply overseen case?

[JanTvrdik]

That's currently expected behavior. There is no standard regarding how to handle multi-line phpDoc tags. If someone figure out how to handle multi-line phpDoc tags consistently, I'll be open to implementing support for them.

[JanTvrdik]

For example consider the following

/**
 * @return iterable
 *  
 * <strong>Lorem</strong>
 */

Does the function return iterable or iterable<strong>?

---

Or consider the following

/**
 * @return Foo
 * Bar
 */

Is Bar description of the @return tag? Or not?

[Majkl578]

Since the phpDoc I provided is indented and has no empty newline between the types, I'd expect it to work.

Both examples you provide are different - not indented and/or separated by empty line.

This is pretty much similar i.e. to:

return $foo === 123
    || $foo === 456
    || $foo === 789;

[ondrejmirtes]

I'm with @JanTvrdik here - the syntax Doctrine uses is just weird. Whitespace in phpDocs is not significant so we can't rely on indentation. (Don't mention that newlines are also whitespace please.)

[JanTvrdik]

@Majkl578 I'm not saying, it's not solvable, but that it requires lots of hours to make sure we design the grammar properly. If we are not super careful, it will cause more problems that it will solve. And it's also entirely possible that after 10 hours of analysis we may simply come to the conclusion that it's better to not support multi-line tags at all.

[Majkl578]

Understood, it doesn't look that hard for @return, but I can't actually imagine it i.e. for @param. Anyway I just thought to report it and see the discussion around.
I'll leave it up to you if you want to close it or investigate further.

[Majkl578]

Btw PhpStorm is failing on this one as well:

[ondrejmirtes]

Any follow up on this? I'd rather close this since it's not economical to address this.

[JanTvrdik]

It's currently waiting for PSR-5 to know whether it should work and how specifically it should work.
There is nothing reasonable that can be done before PSR-5 is approved.

[github-actions]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.