Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.
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
Comment | File | Size | Author |
---|---|---|---|
#3 | 2876789-enable-drupal-function-comment.patch | 449 bytes | mchelen |
Comments
Comment #2
mchelenComment #3
mchelenComment #4
mchelenComment #5
jonathan1055 CreditAttribution: jonathan1055 as a volunteer commentedIs 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?
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?Comment #6
klausiThere 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.
Comment #7
jonathan1055 CreditAttribution: jonathan1055 as a volunteer commentedThanks 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.