It looks like we don't always include $form and $form_state @param directives in DocBlock comments, and I'm told we're meant to exclude them. However, I don't find any mention of such a policy in the Doxygen and comment formatting conventions. If we have one, I propose we document it there. If not, then we're missing a lot of @param directives in core. (The Drupal Code Sniffer flags their omissions as errors.)

Comments

traviscarden’s picture

traviscarden commented
Title: Define and document@param $form/$form_state policy » Define and document @param $form/$form_state policy
jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Active » Fixed

http://drupal.org/node/1354#forms
has the examples for the structure that was discussed and agreed upon a while back on another issue.

I just added a note so that it explicitly mentions not putting in those @param and @return values, which I thought was there but apparently not.

traviscarden’s picture

traviscarden commented

Thanks, @jhodgdon! I've filed #1512368: Don't complain about missing $form/$form_state @param directives in the Drupal Code Sniffer queue.

Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for 2 weeks with no activity.