[PSR-5] Please think about inline docblock uses of 3rd party SA tools

28 views

Skip to first unread message

Gabriel O

unread,

Dec 16, 2018, 1:59:37 PM12/16/18

to PHP Framework Interoperability Group

I don't think current draft clearly allows annotations like

/** @SuppressWarnings(PHPMD) */ which PHPMD uses

or

/** @psalm-suppress PossiblyFalseArgument */ which Psalm uses

Notice that what is different is these don't specify variable they are associated to and they are often used inline. 
Hence they don't necessarily precede structural element according your definition. What these precede in the wild varies a lot.

One weirdest example from our real world code which definitely don't conform your ABNF definitions of structural elements:

/** @psalm-suppress InvalidArrayOffset https://github.com/vimeo/psalm/issues/925 */
$this->{self::CLASSES_USING_CUSTOM_CALLBACK[$className]}($object);


Actually according interpretation of authors of PHP-CS-Fixer, PSR-2/PHPDocumentator forbids this. 
Reason for this is that it's controversial if succeeding line is considered structural element.

I would like to see PSR-5 clarify such usages.