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.