hook_entity_info doc header has a couple of omissions

Thanks for reporting these issues!
- revision table is indeed missing -- it either needs to be removed from the example if the example is wrong, or documented in the doc header if the example is right. Probably the latter, but it should be verified.
- Agreed on 'fieldable'. Probably should say "Set to TRUE if you want your entity type to accept fields." or something to explain what fieldable means.

I verified revision table -- entity_get_info() uses it, so it must be real. Appears to be optional.

Patch attached...

The field attach API page says: "hook_entity_info() is the central place for entity types to define if and how Field API should operate on their entity objects. Notably, the 'fieldable' property needs to be set to TRUE."

It seems this is not the case. 'fieldable' => FALSE only prevents field_ui.module from putting the entity in the field UI for modification. You can still create an entity in code and have bundles and fields attached to it.

..er, right? :-)

Regarding 'fieldable'... I grepped through the code to see how 'fieldable' is being used. What I found:
- entity_get_info() sets it to FALSE by default, but hook_entity_info() sets it to TRUE for the core 'comment', 'node', 'user', and 'taxonomy_term' entities (but FALSE for 'taxonomy_vocabulary', huh, I didn't realize that was an entity too).
- entity_form_submit_build_entity() uses it to decide whether there are field values in the submitted form and to therefore omit them from the entity it builds up.
- DrupalDefaultEntityController::attachLoad() only loads fields via field_attach_load() if it's TRUE
- As noted in #4, the field_ui module uses it to decide whether to display the field UI or not

Since attachLoad() only loads the fields for fieldable types, I would say that a type has to be marked as fieldable for fields to work properly.

As an additional note, entity form building (for the instance editing form) and entity form submissions are not done through the entity controller. Instead, they are handled by the individual entity type's functions (e.g., node_form(), node_save(), etc.). So for instance node_form() and node_save() know that 'fieldable' is TRUE for nodes, and they call field_attach_form(), field_attach_update(), etc. to build the field form components and save the fields. Presumably a different entity that isn't fieldable wouldn't call the field_attach_* functions in its form builder and entity save functions.

So. In summary, while it's technically correct that you can use code calls to attach fields to bundles of entities that have 'fieldable' set to FALSE, I wouldn't say that these fields are actually "attached" in the sense that they would actually work as you would expect. So I think it is fine to leave the documentation on 'fieldable' saying that it defines whether an entity can have fields attached.

Thanks very much, jhodgdon. :-) Spotlight apparently isn't as thorough as grep.

Looks like I get to subclass DrupalDefaultEntityController. I'm trying to make a data entity that might not have a UI.

Meanwhile, after all that digression, the doc patch in #3 still needs a review.

I reviewed the patch and it does add the info discussed here - looks good

marking rtbc as per kim-day's review

Needs to go to d8 and then d7

Committed to 8.x. Moving to 7.x.

Committed to 7.x. Thanks!