hook_field_purge_field and hook_field_purge_instance are not documented.

Info on these:
hook_field_purge_field [see function field_purge_field() in modules/field/field.crud.inc]
hook_field_purge_instance [see function field_purge_instance() in modules/field/field.crud.inc]

Part of #675046: Make sure all hooks in D7 have documentation

CommentFileSizeAuthor
#9 777092c-01.patch1.64 KBpuregin
#4 777092c.patch1.61 KBjhodgdon
#2 777092b.patch1.6 KBjhodgdon
#1 777092.patch2.9 KBjhodgdon

Comments

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Active » Needs review
StatusFileSize
new 777092.patch2.9 KB

Here's a patch.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
StatusFileSize
new 777092b.patch1.6 KB

whoops, must be getting tired. I forgot to revert that last patch. Sigh. Here's a patch with just the intended changes for this issue.

Status: Needs review » Needs work

The last submitted patch, 777092b.patch, failed testing.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Needs work » Needs review
StatusFileSize
new 777092c.patch1.61 KB

OK, here's one that should be right... I hope...

aspilicious’s picture

aspilicious commented
Status: Needs review » Needs work

DELETED COMMENTS

I was wrong, hooks have to be in the imperative form...

aspilicious’s picture

aspilicious commented
Status: Needs work » Needs review

Back to needs review

puregin’s picture

puregin commented

@aspilicious: I'm new to this (or rather back after an absense), so I was just looking into the doc standards. Looks like #487802: Function doc standard for Drupal is non-standard in industry has determined that the standard should be changed to "3rd person declarative" for summary lines.

Having a look at the rest of the patch now...

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

Please read the doc standards page
http://drupal.org/node/1354

It describes our current standards. That issue is old, and we have different standards for hook *definitions*

puregin’s picture

puregin commented
StatusFileSize
new 777092c-01.patch1.64 KB

The descriptions are good, and the examples make sense. Should we mention what the @return value is?

The attached patch changes the summary lines to 3rd person declarative.

puregin’s picture

puregin commented

@jhodgdon thanks for the reference to the new standards. Do you have a pointer to the discussion re: imperative vs. declarative for hooks? Thanks!

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

No, not off-hand and no time to search for it. Good luck on that. :)

As you can see on the doxygen standards page, we do not include @return when there is no return value, which there isn' t for these functions.

And, if you read the section on "hook descriptions", you will find that for hooks that my patch in #4 has the correct verb cases
and the one in #9 is incorrect.
http://drupal.org/node/1354#hooks

blg@bgreenaway.com’s picture

blg@bgreenaway.com commented
Status: Needs review » Reviewed & tested by the community

This issue is now one of merely the verb case, as all other concerns are in fact fixed (equally) by both patches.

In reference to jhodgdon#4 and puregin#9 a comparison with the list of currently documented (and approved) hook descriptions for D7 here http://api.drupal.org/api/group/hooks/7 clearly shows patch at #4 jhodgdon's is the correct (& more consistent) patch. Verb 'ACT' rather than 'ACTS'.

The linked page shows roughly 10-15% of documented hooks are so far in error in this regard where both execute and executes exist in the docs, declare and declares exist in the doc, alter and alters exist in the doc and many more examples of both plural and singular verb case.

Look for the most common case type, and that is the singular case. As node/1354 points out api.drupal.org standard for hooks is the singular type case. So #4 is both correct, by standards, and passes simpletest testing.

Please commit the patch by jhodgdon, 777092c.patch in comment #4.

dries’s picture

dries commented
Status: Reviewed & tested by the community » Fixed

Committed to CVS HEAD. Thanks.

Status: Fixed » Closed (fixed)

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