Page MenuHomePhorge
Create Task
Maniphest T15923

Make all PHPDoc @param have variable names
Closed, ResolvedPublic
Actions

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.

Revisions and Commits

rP Phorge
D25794rPb44b566b1334 Add missing variable names to PHPDoc @param of methods
rARC Arcanist
D25799rARC04e3e250f7da Add missing variable names to PHPDoc @param of methods

Related Objects

Event Timeline

aklapper created this task.Tue, Aug 20, 15:55
Herald added subscribers: Cigaryno, Matthew, chris, tobiaswiese. · View Herald TranscriptTue, Aug 20, 15:55
aklapper added a revision: D25794: Add missing variable names to PHPDoc @param of methods.Tue, Aug 20, 16:08
aklapper added a comment.Wed, Aug 21, 13:06

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).

aklapper closed this task as Resolved by committing rPb44b566b1334: Add missing variable names to PHPDoc @param of methods.Wed, Aug 21, 13:06
aklapper claimed this task.
aklapper added a commit: rPb44b566b1334: Add missing variable names to PHPDoc @param of methods.
aklapper added a revision: D25799: Add missing variable names to PHPDoc @param of methods.Fri, Aug 23, 10:56
aklapper added a commit: rARC04e3e250f7da: Add missing variable names to PHPDoc @param of methods.Fri, Aug 23, 16:52
Content licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) unless otherwise noted; code licensed under Apache 2.0 or other open source licenses. · CC BY-SA 4.0 · Apache 2.0