Rector: Automatically add @throws to docblock

[Aerendir]

I'm checking an app with Psalm and it signals over 800 missing throws docblock.

Adding manually all the throws docblock is an almost infinite work as, once you add a throw docblock, then you need to add it also to the method that uses the just annotated method, and then you need to add it to method that uses the second annotated method, and then add the dockblock to the fourth, ecc.

It is a never ending work that requires hours and hours of work.

I think that this really time consuming and boring work could be well automated by Rector.

However, I think this is also something different from the rectors implemented until now.

To completely implement all throws dockblock, in fact, Rector needs to analyze the code, then add the throws docblocks, then analyze the code again, and then add again the throws docblocks, and then analyze the code again and so on, until it doesn't find any new thrown but not catched throwable.

Do you think it is possible in theory, to add a rector that automatically add all throws dockblocks?

• [ ] Support \Throwables generated by methods or functions (throw $this->createException() and throw createException())
• [ ] Support \Throwables assigned to variables ($value = new \Exception())[https://github.com/rectorphp/rector/pull/2833#discussion_r377556485]
• [ ] Aliased imports (two exceptions with the same name, but different namespaces and one of them is aliased)

[TomasVotruba]

I think that this really time consuming and boring work could be well automated by Rector.

Agreed :+1:

How would you detect class methods that should have this @throws?

[Aerendir]

I don't know... I'm getting confident in using PHPParser.

For the moment I know I can add for sure throwable thrown by a method like:

public function aMethod()
{
    throw new \RuntimeException('This exception can be added to DocBlock');
}

Not sure how to proceed to intercept exceptions thrown by methods and functions used in another method, like:

aMethod($anObject)
{
    $anObject->thisMethodThrowsAnException();
}

But for the moment also if it will be possible to annotate "direct" exceptions it will reduce the time consumed to annotate the code!

I'm going to write some unit tests to cover cases at which I think...

I will submit a PR ASAP.

[Aerendir]

Where should have I to add the new rector?

[Aerendir]

Some places:

• Rector\CodeQuality\Exception
• Rector\CodingStyle\Rector\ClassMethod
• Rector\PhpDoc

The last one seems to me the best: WDYT @TomasVotruba ?

[TomasVotruba]

CodingStyle sound the best

[Aerendir]

Yes, I was just thinking at this... I'm going to write the tests...

[TomasVotruba]

For the moment I know I can add for sure throwable thrown by a method like:

Let's start with this and make it work first.

[TomasVotruba]

You can use bin/rector create command to create the most of the code. In case you don't use it yet

[Aerendir]

Ok, I'll give it a try: thank you!

In the mean time, the tests are ready...

[TomasVotruba]

Great job :+1:

Send it as PR always so I can comment and CI can help. Even if it's a draft

[TomasVotruba]

Closing in favor of #2861