Page MenuHomePhorge

Make all PHPDoc @param have variable names
Closed, ResolvedPublic

Description

Current PHPDoc headers for methods across Phorge classes (ignoring stuff under /external/) have a mix of @param definitions in two styles:
@param typeOrClass Explanation (without variable name) and
@param typeOrClass $variablename Explanation (with variable name).

While PHPDoc is still an informal standard, I'd like to stick to include the "variable name" for clarity.

Furthermore, PHPStan throws output about variable names missing, so it's harder to find actual issues (e.g. non-existing types/classes of parameters, or invalid return types) or future PHPDoc improvements (e.g. replacing wild with mixed) in all that output noise.

Event Timeline

Ironically, adding missing variable names to @param lines increases the amount of errors in PHPStan output:

While there are now less PHPDoc tag @param has invalid value (type|class Explanation of): Unexpected token "Explanation", expected variable at offset 123 lines, PHPStan being able to find and parse types/classes in PHPDoc creates more additional Parameter $foo of method ChildClass::overwrittenMethod() has invalid type wild. errors accompanied by Access to offset 'bar' on an unknown class wild. errors.

Testing a few entries in Diviner, the patch in D25794 literally does not seem to change anything - results before and after are still the same, which means that Diviner is kind of smart in this aspect (and also not smart due to the 404s I get for methods indexed by the Diviner Search but only rendering a non-existing page).