Check that hooks follow documentation standards

[JDGrimes]

Forked from #241 (comment).

[GaryJones]

Even if the full filter DocBlock couldn't be fully checked yet, at least allowing DocBlocks before lines that contain add_filter(, do_action(, do_action_ref_array(, or apply_filters_ref_array(, would allow us to remove the Squiz.Commenting.BlockComment.WrongStart exclusion, so it can highlight any incorrect DocBlocks elsewhere.

(Actually, because of the need to ignore /** translators: ... */ too, this probably needs a bit more thought on it's own.)

[apermo]

Hi — I built an independent implementation of this for my own apermo-coding-standards package.

Note: The code was written with major AI assistance, so it cannot be reused directly due to WPCS licensing policy — but the design decisions and edge cases encountered should be helpful.

What the sniff checks

The sniff (Apermo.Hooks.RequireHookDocBlock) covers all six hook invocation functions:

• do_action, do_action_ref_array, do_action_deprecated
• apply_filters, apply_filters_ref_array, apply_filters_deprecated

It issues warnings (not errors) for three cases:

1. Missing — Hook call has no /** */ doc block immediately before it. Regular // comments don't count.
2. MissingParam — Doc block exists but has no @param tags when the hook passes arguments.
3. MissingReturn — Filter doc block is missing a @return tag.

Key design decisions

• Looks backward from statement start — We use findStartOfStatement() to handle cases like $result = apply_filters(...), then walk backward skipping whitespace to find a T_DOC_COMMENT_CLOSE_TAG.

• Skips method calls — The sniff checks the preceding token for ->, ::, or ?-> to avoid false positives on $obj->do_action() or SomeClass::apply_filters().

  • Skips function declarations — If the preceding token is T_FUNCTION, it's a declaration, not a call.
  • Smart argument counting:
    • Standard variants: counts parameters beyond the hook name (param 1).
    • _ref_array variants: inspects the second parameter — if it's an empty array literal ([] or array()), treats it as zero arguments.
    • _deprecated variants: same handling (param 2 is the args array; params 3+ are deprecation metadata, not hook args).
    • Uses PHPCSUtils\Utils\PassedParameters for reliable parameter extraction.
  • No @param count matching — We deliberately don't check whether the number of @param tags matches the number of hook arguments. We only check "has at least one @param when arguments exist." This keeps the sniff simple and avoids false positives with complex/conditional argument passing.

  Links

  • Initial implementation: apermo/apermo-coding-standards@c6cceb5
  • Fix for whitespace in array() detection: apermo/apermo-coding-standards@948aeeb
  • Sniff source: https://github.com/apermo/apermo-coding-standards/blob/main/Apermo/Sniffs/Hooks/RequireHookDocBlockSniff.php
  • Unit test + fixture: https://github.com/apermo/apermo-coding-standards/blob/main/Apermo/Tests/Hooks/RequireHookDocBlockUnitTest.php

  Edge cases we encountered

  • array ( ) with spaces inside — the regex for empty array() detection initially didn't account for whitespace between array, (, and )
  • do_action_deprecated takes the args array as param 2 and deprecation info (version, replacement) as params 3+, so argument counting can't just use total param count
  • apply_filters_ref_array similarly bundles all hook args into a single array parameter
  • $obj->apply_filters() and SomeClass::do_action() — not uncommon in codebases that wrap hook functions

  Hope this helps move the ticket forward!

[kkmuffme]

Especially "@return" and "@returns" on apply_filters and do_action are common incorrect docs in WP