Re-check all form types inherited options

[javiereguiluz]

Some form types extend other parent types (e.g. CountryType and EnumType extend ChoiceType). In the docs of the child classes, we display all options defined by them and all options defined by their parent types.

However, we handle this manually, so we miss options from time to time (this is a recurrent problem; see #2360).

So, we have two options:

• Re-check all options again and fix errors manually
• Re-think how we solve this

About rethinking:

• We could just list the names of all the inherited options and link to the parent descriptions, instead of embedding all the descriptions in all child constrains
• We could add some PHP logic in the docs-builder tool used to build docs to fix this somehow

Thoughts?

[OskarStark]

We could just list the names of all the inherited options and link to the parent descriptions, instead of embedding all the descriptions in all child constrains

Would be easier to maintain, but harder to consume by the user IMHO

We could add some PHP logic in the docs-builder tool used to build docs to fix this somehow

Would avoid manual errors, but hard to achieve with versionadded directives, without comparing to older branches I think.

[MrYamous]

As a first step of simplification, instead of including the options one by one, could we group them together in a parent class file and include that ? This implies that we can use include in an rst.inc file, I don't know if that's possible.

This would allow, if we take EnumType as an example, to include a file like choice_options.rst.inc which would itself include the twenty files for the different options.
Then, if a ChoiceType option is added tomorrow, we only have to add it in one place, without having to check every type that inherits from ChoiceType.

[stof]

This won't work well with the overriden options section, which handles some of the parent options in a special way (and so they must be excluded from inherited options)

[yceruto]

An automated script to sync this doc with its code would be great here.

this reminds me that I wrote this project some years ago: https://github.com/phplancer/symfony-form to explore this idea using the debug:form command, which exposes all this information easily in JSON format (using the --format=json option).

with debug:form --format=json, we will get all builtin_form_types, then go in with debug:form ChoiceType --format=json to gather all options (grouped into "own", "overridden", "parent" and those that come from "type extensions"), then go deeper with debug:form ChoiceType choice_filter --format=json to get the option details.

we could run it per Symfony version and generate a diff to know when we should add a versionadded directive with a generic text.

the missing part would be how to link each form type and its options with their corresponding documentation… maybe using some naming conventions to load it!? And if the doc doesn't exist, we can always display the option "info" (if provided) as a fallback doc.

I can help with this if it works for you, but I’d need to explore the building system first to understand it better.