Rechecking inherit options

[wouterj]

Form Types can be represented with a tree. Some types inherits each other and all form types inherits the field type (as of Symfony 2.0, form in 2.1).

We currently have a Inherit options section in each reference article with some relevant inherit options. In order to keep this up to date, someone needs to:

• Recheck every parent/child relation (is it correct? is there a link?)
• Recheck the inherit options. Are they relevant? Are their other relevant
  options that should get placed here?
• Add a list of links to the description of some options which are not
  relevant enough to get documented on this page. This to avoid long
  articles.

A 'tree' of all parent/child relations (in 2.0) and their options can be found in this gist.

[xabbuh]

I checked all form types for their parent types and links to the API docs of their classes. They are all fine.

When it comes to options, I see one issue first: the order of options. To me, it seems as if options are ordered mainly randomly inside their sections (section meaning one of Options, Inherited Options, Overridden Options). I don't think that this a good way. When people use the reference to find out what a particular option does. With the current situation, they would look at the list of options on top of the page which may be very long depending on the form type. Without some luck or using the search function of your browser, you may easily overlook the option you were look for.

Seeing this from a development experience point of view, that's not really satisfying and I think we can do better. For example, we can order the options in each section in alphabetical order. In the worst situation, you would only have to check three possible positions (the option you are looking for can be in any of the three sections). I think that would make it much easier to find the particular option you are looking for.

What do you think?

[wouterj]

I checked all form types for their parent types and links to the API docs of their classes. They are all fine.

Great as always! I've marked it as done

What do you think?

100% agree with your idea. +1 for alphabetical order

[xabbuh]

I have to correct myself. Obviously, I didn't look carefully enough. The parent types of the email and the textarea types have to be fixed (see #4063 for the fix).

[xabbuh]

The options are now ordered alphabetically. So, if anyone is willing to step up checking the options. :)

[weaverryan]

Perhaps (see #4152) we should explicitly add a todo in this issue to add the attr option to everything?

[wouterj]

Yes, we should make this issue more concrete when we have specific tasks to do.

[xabbuh]

Should we somehow define what we understand by "relevant options"? So, that someone who wants to pick this know what to look after?

[javiereguiluz]

This issue is ivery old but it seems very important. Which is the real state of the issue? Do we have an updated list of the options defined by all form fields for 2.6 or 2.7? Thanks.

[roenschg]

Today I wanted to change the translation domain of a text field and the option wasn´t in the documentation at http://symfony.com/doc/current/reference/forms/types/text.html

I found the option later by clicking on the following link: http://symfony.com/doc/current/reference/forms/types/form.html

Should we document all inherited options or just "relevant" ones?

[vudaltsov]

@javiereguiluz , is this issue still relevant?

[javiereguiluz]

I'm afraid it's still relevant. Someone should very carefully check if all options (including inherited ones) are listed for all form types. It's a extremely boring and time-consuming task :(

[javiereguiluz]

I'm closing as fixed because in #12302 we added the missing attr option to all types ... and all of them look complete now. If we find some issues, let's fix them on future pull requests. Thanks!