PhpDocParser: add config for lines in its AST & enable ignoring errors within phpdocs

[janedbal]

This allows custom rules to properly report exact lines of e.g. @param tags when needed.

[phpstan-bot]

You've opened the pull request against the latest branch 1.11.x. If your code is relevant on 1.10.x and you want it to be released sooner, please rebase your pull request and change its target to 1.10.x.

[ondrejmirtes]

I'm looking forward to this! I'd like a proof of concept of using this in some 1st party PHPStan rules here that report things about PHPDocs. It should probably be done through some helper class so that we have logic in a single place that makes sure "Do we have the lines? Report precise lines. Otherwise report the line with the method declaration" that would apply this only to bleeding edge.

One of the challenges we'll face is ignoring errors I think. Right now you can ignore errors like this: https://phpstan.org/r/31387e59-5309-44f9-8a54-eeff03762cc7

But if line 6 gets reported instead of line 8 then we need to do something about ignoring errors too.

[ondrejmirtes]

Also - after we merge this, please also checkout 1.11.x and make sure that @phpstan-ignore works as expected. It's a new way to ignore errors with identifiers and it automatically decides if the error to ignore should be on the current line, or the next line.

So somehow it should work inside PHPDocs too.

[janedbal]

Should I update docs somehow? The broken edgecase was never documented: https://phpstan.org/user-guide/ignoring-errors

/**
 * @phpstan-ignore-next-line
 *
 * This is the legacy behaviour, the next line is meant as next-non-comment-line
 */
fail();

I'd say it even states the fixed one :D

Both @phpstan-ignore-line and @phpstan-ignore-next-line ignore all errors on the corresponding line.

[ondrejmirtes]

Should I update docs somehow?

No, it's okay, with that test I was just testing the behaviour to prove the fact that "next line" means "next line after this PHPDoc"

[ondrejmirtes]

@janedbal If you rebase now the build should not fail because of Rector anymore (after I wrote 1.5k lines in simple-downgrader, 3.5k if you include tests 😂 )

[janedbal]

Rebased.

[ondrejmirtes]

Awesome, thank you!

[gnutix]

No, it's okay, with that test I was just testing the behaviour to prove the fact that "next line" means "next line after this PHPDoc"

I think this behavior is now broken @ondrejmirtes. I just upgraded and started getting :

 ------ ---------------------------------------------------------------------------------------------------------------------------------------------------- 
  Line   src/.../SomeClass.php                                                                         
 ------ ---------------------------------------------------------------------------------------------------------------------------------------------------- 
  167    No error to ignore is reported on line 167.                                                                                                         
  168    Method App\...\SomeClass::getFunctions() return type has no signature specified for Closure.  
 ------ ---------------------------------------------------------------------------------------------------------------------------------------------------- 

For code :

    /**
     * @phpstan-ignore-next-line I have no idea how this Closure is typed, that's the point...
     *
     * @return array<Closure|DeferredEvaluation>
     */
    private function getFunctions(Context $context): array
    {
         // ...
    }

If I change it to the following, then it works again :

    /**
     * @return array<Closure|DeferredEvaluation>
     */
    /** @phpstan-ignore-next-line I have no idea how this Closure is typed, that's the point... */
    private function getFunctions(Context $context): array

[janedbal]

@gnutix That is intentional. Now (with bleeding edge), next line means actual next line. See phpstan/phpstan#10374