Problem/Motivation

Static analysis tools (such as drupal-check) expect iterable param and iterable return types to be documented, but drupal/coder requires that hook implementations not provide their own @param and @return documentation - see https://git.drupalcode.org/project/coder/-/blame/8.3.x/coder_sniffer/Dru...

Steps to reproduce

Install mglaman/drupal-check v1.4.0 and drupal/coder; enable the Drupal phpcs rule; run drupal-check and phpcs on a contrib project with hook implementations.

drupal-check flags that each hook implementation's iterable param and return types need to be documented (Function has parameter with no value type specified in iterable type array. 💡 See: https://phpstan.org/blog/solving-phpstan-no-value-type-specified-in-iter...), while phpcs flags that they should not be documented ("Hook implementations should not duplicate @param documentation").

Proposed resolution

Either static analysis tools should be somehow configured to ignore such issues re: hook implementations, or the sniff should allow potentially redundant documentation of hook implementations. See also https://github.com/mglaman/phpstan-drupal/issues/404

Comments

mfb created an issue. See original summary.

klausi’s picture

klausi
he/him||they/them
Primary language German
Location 🇦🇹 Vienna
commented

From the Drupal coding standards https://www.drupal.org/docs/develop/standards/api-documentation-and-comm... "Do not document parameters and return value though -- these are documented on the hook definition referenced in the summary line."

So drupal-check is wrong on this and ideally it should be fixed there. We could also remove this in Coder, but would only do that if it is very hard to fix in drupal-check.

mfb’s picture

mfb
they or he
commented

I also filed https://github.com/mglaman/phpstan-drupal/issues/404 - not sure if this would be addressed in phpstan-drupal or drupal-check :)

mfb’s picture

mfb
they or he
commented
Issue summary: View changes

(Added description of the warning message from phpstan.)