It is no secret that the documentation of the form API is not in great shape. Today Merlin said on IRC that "the design does not lend itself to being well documented" and he is, of course, right. There were proposals during the years to convert everything to object oriented code but IMO that's too much in one fell swoop. I have the idea to use ArrayObject-based objects -- now that #type matters little -- and keep the current functions -- no methods. The properties will become doxygenable so the documentation is right there in the code, reusable by API module, IDEs etc. Here is some sample code.

So the changes:

1. Change ['#foo'] to ->foo
2. Change $form['x'] = array('#type' => 'whatever') to $form['x'] = new DrupalFormWhatever(array(
3. Change foreach(element_children($form) as $key) $child = &$form[$key] to foreach ($form as $child)

Best of all, most of this change is scriptable -- the first two is likely to be easy with regular expressions, the third IMO needs some more scripting as we usually do $form[$key].... First reaction are: Merlin is excited, frando warned that most functions expecting arrays like array_merge wont work which is not ideal but we rarely do operations like that with form children. We now need someone to actually do this right now and then during the long winter of code freeze we can add documentation of the properties.

Commenting on this Story is closed.