Prevent Squiz.Commenting.FunctionCommentThrowTag.Missing failing for exceptions caught in method

[josemv92]

Describe the bug
Using the Squiz.Commenting.FunctionCommentThrowTag.Missing to warn when a method is throwing an exception not mentioned in the PHPdoc is requiring users to add the @throw tag even when the exception is caught in the same scope of the method.

Code sample

class MyClass {

    /**
     * Test method.
     *
     * @return void
     */
    public function myMethod() {
        try {
            throw new Exception("Error");
        } catch (Exception $e) {
            return false;
        }
    }
}

Custom ruleset

<?xml version="1.0"?>
<ruleset name="Custom">
    <rule ref="Squiz.Commenting.FunctionCommentThrowTag.Missing" />
</ruleset>

To reproduce
Steps to reproduce the behavior:

1. Create a file called test.php with the code sample above.
2. Run phpcs test.php
3. See error message displayed

FILE: /test.php
--------------------------------------------------------------------------------------------------------
FOUND 1 ERROR AFFECTING 1 LINE
--------------------------------------------------------------------------------------------------------
 9 | ERROR | Missing @throws tag in function comment
   |       | (Squiz.Commenting.FunctionCommentThrowTag.Missing)
--------------------------------------------------------------------------------------------------------

Expected behavior
The rule shouldn't trigger for users to set the @throws tag on the method PHPdoc since in the end the method won't be throwing this exception outside of its scope.

Versions (please complete the following information):

• OS:Ubuntu 20 (but it might be happening in any).
• PHP: 7.4+
• PHPCS: 3.7
• Standard: Squiz

Additional context
This is conflicting with other inspections applied by some IDEs (like PHPStorm) which indicates the @throws tag is not necessary.

[ArneGockeln]

We are facing the same behaviour in PhpStorm 2022.2.3 on macOS Monterey 12.6 and also in the automated phpcs test pipelines on azure cloud.

[Daniel217D]

Any updates on this?

[celorodovalho]

Any updates on this issue?

[jrfnl]

@celorodovalho As far as I can see, nobody has submitted a PR to fix this, so no.

[celorodovalho]

@jrfnl I could submit it by myself if I have time to learn how it works.

[jrfnl]

@celorodovalho If you do, please make sure you submit the PR to the new repo. This repo is abandoned and https://github.com/PHPCSStandards/PHP_CodeSniffer is its successor. See: #3932