Skip to content

Split ParamReturnAndVarTagMalformsFixer into single-task doc block rules#86

Merged
TomasVotruba merged 2 commits into
mainfrom
tv-split
Jun 9, 2026
Merged

Split ParamReturnAndVarTagMalformsFixer into single-task doc block rules#86
TomasVotruba merged 2 commits into
mainfrom
tv-split

Conversation

@TomasVotruba

Copy link
Copy Markdown
Member

Split ParamReturnAndVarTagMalformsFixer into single-task rules

The all-in-one ParamReturnAndVarTagMalformsFixer mixed ~10 unrelated doc-block fixes behind one rule. This splits it into focused, single-task rules — each fixes one kind of @param/@return/@var malform, so they can be enabled, skipped and reasoned about individually.

  • shared token traversal lives in a new AbstractDocBlockFixer base; each rule only implements its own processDocContent()
  • the old MalformWorker classes + MalformWorkerInterface are removed (logic inlined into the rules)
  • ParamReturnAndVarTagMalformsFixer is kept as a deprecated, empty rule implementing DeprecatedFixerInterface, pointing at its successors
  • all rules registered together in a new config/sets/docblock.php set, imported from config/symplify.php
  • all rules handle the @phpstan- and @psalm- prefixed tag variants

New rules

AddMissingParamNameFixer — add a missing variable name to a @param

 /**
- * @param string
+ * @param string $name
  */
 function getPerson($name)
 {
 }

AddMissingVarNameFixer — add a missing variable name to an inline @var

-/** @var int */
+/** @var int $value */
 $value = 1000;

DoubleAsteriskInlineVarFixer — use a /** doc block for an inline @var comment

-/* @var int $variable */
+/** @var int $variable */
 $variable = 5;

FixParamNameTypoFixer — fix a typo in the @param name to match the real argument

 /**
  * @param string $one
- * @param string $twoTypo
+ * @param string $two
  */
 function anotherFunction(string $one, string $two)
 {
 }

RemoveDeadParamFixer — remove a dead @param line that has only a name and no type

 /**
  * @param string $name
- * @param $age
  */
 function withDeadParam(string $name, $age)
 {
 }

RemoveParamNameReferenceFixer — remove the reference & from a @param name

 /**
- * @param string &$name
+ * @param string $name
  */
 function paramReference($name)
 {
 }

RemoveSuperfluousReturnNameFixer — remove a superfluous variable name from @return

 /**
- * @return int $value
+ * @return int
  */
 function function1(): int
 {
 }

RemoveSuperfluousVarNameFixer — remove a superfluous variable name from a property @var

 /**
- * @var string $property
+ * @var string
  */
 private $property;

SingleLineInlineVarDocBlockFixer — collapse a multi-line inline @var doc block into one line

-/**
- * @var int $value
- */
+/** @var int $value */
 $value = 1000;

SwitchedTypeAndNameFixer — reorder switched type and variable name

 /**
- * @param $a string
- * @param $b string|null
+ * @param string $a
+ * @param string|null $b
  */
 function test($a, string $b = null): string
 {
 }

Tests

  • each rule gets its own tests/Fixer/Commenting/<Fixer>/ dir (test + isolated fixtures, moved via git mv)
  • combined/interplay/skip fixtures moved to a new tests/Set/DocblockSet/ integration test that runs the whole docblock set, so no coverage is lost

Verification

ECS, Rector (dry-run), PHPStan and the full PHPUnit suite (160 tests) all pass.

@TomasVotruba TomasVotruba merged commit c2fdcdf into main Jun 9, 2026
6 checks passed
@TomasVotruba TomasVotruba deleted the tv-split branch June 9, 2026 23:10
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