Fixer breaks PhpDoc before return

[f1amy]

Bug report

Description

phpdoc_to_comment rule breaks PhpDoc that is used to declare returned value from within a function.

Runtime version

PHP CS Fixer 3.28.0 Jump & Run by Fabien Potencier and Dariusz Ruminski.
PHP runtime: 8.2.11

Used command

php ./vendor/bin/php-cs-fixer fix --allow-risky=yes --config=.php-cs-fixer.dist.php

Loaded config default from ".php-cs-fixer.dist.php".
Using cache file "/srv/app/var/tools/.php-cs-fixer.cache".
.........F................................................                                                                                                                                                                  58 / 58 (100%)
Legend: .-no changes, F-fixed, S-skipped (cached or empty file), I-invalid file syntax (file ignored), E-error
   1) /srv/app/src/Infrastructure/State/Order/OrderGetCollectionProvider.php (phpdoc_to_comment)

Fixed 1 of 58 files in 0.743 seconds, 16.000 MB memory used

Configuration file

<?php

$finder = (new PhpCsFixer\Finder())
    ->in(__DIR__.'/src')
    ->in(__DIR__.'/tests')
    ->in(__DIR__.'/migrations')
;

return (new PhpCsFixer\Config())
    ->setRiskyAllowed(true)
    ->setRules([
        '@Symfony' => true,
        '@Symfony:risky' => true,
        '@DoctrineAnnotation' => true,
    ])
    ->setFinder($finder)
    ->setCacheFile(__DIR__.'/var/tools/.php-cs-fixer.cache')
;

Code snippet that reproduces the problem

Expected:

<?php

function something(): object
{
    /** @var object */
    return $this->get();
}

Actual:

<?php

function something(): object
{
    /* @var object */
    return $this->get();
}

[f1amy]

I have reproduced this on latest version of the tool.

[Wirone]

I believe we need T_RETURN support to CommentsAnalyzer::isValidLanguageConstruct(), with early return true for this token. Adding this token to static $languageStructures list does not solve the problem, because further logic checks for ] or ) and look inside the block, while using parentheses on return is discouraged. @f1amy do you want to prepare the PR with the fix?

[f1amy]

@Wirone I will try

[f1amy]

@Wirone done!