The Drupal.Commenting.FunctionComment sniff should be enabled in the ruleset to adhere to Drupal coding standards.

Drupal documentation standards require that each parameter be documented with @param, and the return value documented with @return. However, the relevant sniff is not enabled in http://cgit.drupalcode.org/coder/tree/coder_sniffer/Drupal/ruleset.xml

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

mchelen created an issue. See original summary.

mchelen’s picture

mchelen’s picture

Title: Enable Squiz.Commenting.FunctionComment » Enable Drupal.Commenting.FunctionComment
Issue summary: View changes
FileSize
449 bytes
mchelen’s picture

jonathan1055’s picture

Version: 8.x-2.x-dev » 8.x-3.x-dev

Is this relevent anymore? At 8.x-3.x (and also at 2.x) it seems that all Drupal.* sniffs are automatically included. There is no specific inclusion of sniffs in coder_sniffer/Drupal/ruleset.xml, it only has customisations such as excluding some sniffs for certain file name patterns. So I'm not sure what the patch above actually achieved?

Drupal documentation standards require that each parameter be documented with @param, and the return value documented with @return.

Yes, you are right. The @return tag is covered by several checks in Drupal.Commenting.FunctionComment. However, I cannot find any sniffs that check that each function parameter has a corresponding @param tag. Maybe that should be on our list to add?

klausi’s picture

Status: Active » Closed (works as designed)

There are many exceptions on certain types of functions where @param/@return docs can be omitted, so it is hard to enforce them as we would get false positives.

Yep, I think we can close this issue, Drupal.Commenting.FunctionComment is enabled and works already.

jonathan1055’s picture

Thanks Klausi, yes checking api-documentation-and-comment-standards#functions there are many alternatives and exceptions for including @param tags. It could be programmed (probably) but would take a lot of effort and I think we have other more important work to do on Coder, so I agree we can leave this as-is.