Documentation for hook_field_delete/update/insert is unclear

Good point. The documentation does say this hook is invoked from field_attach_delete(), which is true... So it's invoked when a field is removed from an entity bundle. The documentation should say this in a clearer manual.

Probably a good Novice project...

Ah, you're right joachim, thanks! It would be invoked from deleting a node, comment, etc. with that field attached to it, to delete the data that is in that particular field instance.

I was confusing field_attach_delete() [which deletes data in a field on a particular entity object, and invokes hook_field_delete()] with field_delete_instance() [which removes a field from a bundle, and invokes hook_field_delete_instance()].

Attached patch contains below proposed wordings

This hook is invoked on the module that defines a field to delete the data that is in particular field instanace. (Just before field_attach_delete() is called.)

There are a couple of problems with this patch:
- Spelling: instanace -> instance
- Accuracy: it is called *from* field_attach_delete, not *before* field_attach_delete.
- Completeness: you left out the part that says it is called just before the data is deleted from field storage, as stated in the original text being replace by this patch.
- Also it needs some grammar cleanup. [let me know if you need assistance with that part]

So much issues :-)
Reworded to this & attached patch.

This hook is invoked on the module that defines a field and just before the data of particular field instance is deleted from field storage in field_attach_delete().

Is it looking good now, let me know if needs more cleanup or so ?

Thanks

Much better. :)
- I would replace the "and" with a comma, and then we're done. "...defines a field, just before the..."
- Needs "a" here: "the data of a particular field instance"

Updated :-)

That looks good to me. joachim - since you reported this, any comment on the proposed change?

I think I'll tenatively set to RTBC and see if anyone objects.

Joachim: Let us know when your breakfast is settled. :) Better wording suggestions will be cheerfully adopted.

Sounds like this still needs review yet. Though FWIW, the wording seems clear to me. :) But I don't eat breakfast. ;)

Well #17 makes it more clear, re-rolled the patch.

Should we say ... data in this field for a particular entity instance is deleted... ?

OK, my mistake. What do you call a particular entity object then?

OK, how about "for the particular entity object" then?

The case is,
entity would be an instance of particular entity type & that means fields have entities not the other way round,
while it currently says that
data in the field which a entity object is carrying would be deleted.
So I think it should be:
"for the particular entity type" ??
Correct me if I am wrong :-)

Um. No, I don't think so. This hook is for responding when a single node, taxonomy term, user, etc. *object* is being deleted, and your module's field needs to do something special with some field data that it is storing outside the normal field system's storage.

So we shouldn't be talking about entity types at all. This is responding to deleting an entity object, by deleting the outside-stored information your module has for that particular field.

How about this [note that I have changed the first line too]:
---
Define custom delete behavior for this module's field data.

This hook is invoked from field_attach_delete() on the module that defines a field, during the process of deleting an entity object (node, taxonomy term, etc.). It is invoked just before the data for this field on the particular entity object is deleted from field storage. Only field modules that are storing or tracking information outside the standard field storage mechanism need to implement this hook.
---

And maybe we could have an @see link to the hook that does the converse (allows field modules to store some outside information when the node/term/etc. object is inserted or updated)? I don't know off-hand what that hook is, but there must be one.

Aha get it, well I guess this doc needs some update too http://drupal.org/node/1261744 or may be I mis-read it.

I don't see anything particularly wrong there, except that I'm not sure it is entirely consistent in its terminology around entity types and entity objects. It's certainly easy to get confused about!

yeah that's what i meant, it's a bit confusing around entity types & entities.
anyways in #28, for @see link, I think it's "hook_field_insert" and "hook_field_update" ?

Yes, those look like the right hooks. Dang, their docs are also very weak and have the same problems as hook_field_delete does... would someone like to expand this patch to put similar explanations in them, or at least put @see references between these three hooks?

Re-rolled the patch along with adding @see references for other two hooks too.

So far, so good, thanks!

Now, can we also add similar information to the update/insert hooks to what we added to the delete hook, saying that they are useful to store information outside the standard field storage mechanism?

Updated patch with similar information. Thanks.

Looks great!

One little problem: "inserted from field storage." on the insert hook -- needs to be "inserted into field storage." :)

Update hook has the same problem: updated from -> updated into.

Yeah 'inserted from' doesn't make much sense either :-) Anyways last patch had trailing whitespaces also, so removed those too.
Thanks

Now, this looks like good documentation. Thanks!

Patch applied to both 8.x and 7.x. Committed to both.