Incorrect "block_name" documentation

[webmozart]

The documentation of the "block_name" option says:

Allows you to override the block name used to render the form type. Useful for example if you have multiple instances of the same form and you need to personalize the rendering of the forms individually.

This is not quite correct. The meaning of that option is a little different than one would expect, I suppose. It only affects block names starting with underscores:

• If setting "block_name" of the root form named "foo" to "custom", it will be possible to customize the rendering in the _custom_widget block instead of _foo_widget
• If setting "block_name" on a child named "foo" of parent "parent" to "custom", the customizable block for that child will be _parent_custom_widget instead of _parent_foo_widget

This feature was mainly needed to support all rows of the collection type collectively in a block _parent_entry_widget instead of _parent_1_widget, _parent_2_widget, ... I don't know if the "block_name" option is really useful other than for that.

[wouterj]

Hmm, I'm not sure I quite get the difference between what the documentation says and what you're explaining with those great examples.

However, I'm +1 for including some examples.

[xabbuh]

I'm not sure either if I really got it. However, I feel that this is one of the options for which we should consider in #2360 how important they really are.

[webmozart]

You know that for each field the following block names are checked in order (assuming a "text" field):

_field_id_widget (e.g. _parent_child_widget)
text_widget
form_widget

The documentation suggests that setting "block_name" to "foo" alters this chain in this way:

foo_widget
form_widget

That's wrong. The actual altered chain is:

_parent_foo_widget (or _foo_widget if there's no parent)
text_widget
form_widget

Clearer?