Skip to content

Keep phpdoc @param on expression statements in blink NoSuperfluousPhpdocTags - #196

Merged
TomasVotruba merged 1 commit into
mainfrom
fix-blink-superfluous-phpdoc-before-expression
Oct 10, 2026
Merged

TomasVotruba merged 1 commit into
mainfrom
fix-blink-superfluous-phpdoc-before-expression

Conversation

@TomasVotruba

Copy link
Copy Markdown
Member

Problem

Running ecs check --blink on the rector codebase stripped a valid closure-param docblock:

/** @param Use_::TYPE_* $useType */
$this->useImportsTraverser->traverserStmts($stmts, static function (int $useType, ...) { ... });

The PHP engine keeps this tag. Blink removed it, leaving /** */.

Cause

signatureAfter() walks forward from a docblock to find the declaration it documents. When the first significant token is a bare variable (here $this), it was treated as a property declaration via parseProperty(), which returns an empty parameter set. With allow_unused_params: false (rector's config), the @param $useType then looked like an unused param and was dropped.

A docblock before an expression statement is not attached to any function or property, so PHP-CS-Fixer leaves it alone.

Fix

Reject a bare variable as the first token after the docblock unless a property modifier/type preceded it. A property declaration never starts with a bare variable (it requires visibility/var/static/readonly or a type), so this only skips expression statements.

Added a regression test covering the closure-param-before-expression case.

Verified on rector-src: the two affected files (AliasUsesResolver, UsedImportsResolver) are no longer mis-fixed.

…docTags

A docblock before an expression statement (e.g. a method call taking a closure) was misread as a property declaration, so its @PARAM tags were dropped as unused params. Reject a bare variable as the first token after the docblock unless a modifier preceded it.
@TomasVotruba
TomasVotruba merged commit f549baf into main Oct 10, 2026
21 checks passed
@TomasVotruba
TomasVotruba deleted the fix-blink-superfluous-phpdoc-before-expression branch October 10, 2026 08:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant