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.



![Popular open source software is more secure than unpopular open source software, because insecure software becomes unpopular fast. [That doesn't happen for proprietary software.]](sites/all/themes/drupal4hu/images/bg-center/bg-center_4.png)















