We should add a sniff that detects if the @param tags match the arguments list.

Cases:

  1. @param tag(s) is/are missing
  2. Variable names are incorrect

We need to be careful about determining when to trigger such warning as there are situations where we're explicitly expected not to document parameters e.g. form generation functions.

Also, this does work sometimes:

/**
 * Creates a blah blah.
 *
 * @param $site
 *   The site node.
 * @param array $domains
 *   An array of domains to remove.
 */
function foo($site) {

Produces:

  802 | ERROR | [ ] Missing parameter type
  804 | ERROR | [ ] Doc comment for parameter $domains does not match actual variable name $site

Comments

psynaptic’s picture

psynaptic commented
Issue summary: View changes
psynaptic’s picture

psynaptic commented
Issue summary: View changes
klausi’s picture

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

That could be tricky, since you must not document the $form and $form_state parameters on form constructors for example. Same for hook implementations. So the checks that we have are a bit conservative and only report mismatches for example.

psynaptic’s picture

psynaptic commented

In the case of form functions, they're supposed to have Form constructor for the foo form. and they're also supposed to have @ingroup forms so at least they should be detectable: https://drupal.org/node/1354#forms

The other cases where we don't need to do this are hook implemenations, which could also (I assume) be detected easily.

Are there other cases that are more difficult to detect?

I think this is one of the most valuable sniffs if it could be implemented. PHP Storm warns about missing documentation, it would be amazing for our CI system to do the same (not all of our engineers use PHP Storm).

psynaptic’s picture

psynaptic commented

Here's some things I think we could detect:

  • Form functions
    • @ingroup forms
    • Form constructor for
    • MODULE_*_form
    • MODULE_*_submit|validate
    • $form, &$form_state
    • $form = array(); and possibly other FAPI indicators
  • Hook implementations
    • Implements...
  • Render callbacks
    • Render API callback:
    • $element, &$form_state, $form
klausi’s picture

klausi
he/him||they/them
Primary language German
Location 🇦🇹 Vienna
commented
Status: Active » Closed (duplicate)

Duplicate of #2624558: Create sniff for missing @param directive when other @param tags exist. @param comments are not required in Drupal, but at least on classes they should be complete for all parameters. I think that is covered now.