Well, improving documentation of this, for the form builder, and for relational segments are on my personal want-to-find-time-to-do list.
But picking on ad_form itself is awfully unfair given that the hardest parts to understand are directly attributable to the form builder which we inherited from aD in largely undocumented and, indeed, incomplete form. I'd love to see all the form builder widgets documented.
For instance if the date "get_property" and "acquire" functions were fully documented, then my comment in the ad_form API header that "to_sql() calls the datatype's get_property proc" would be a useful hint to read that documentation. Unfortunately no data type documents its "get_property" proc so my hint leads to a blank page.
But it ain't *my* fault as the author of ad_form that datatype documentation doesn't exist for the form builder ...
Go pick on Karl Goldstein over this and leave me out of it!
Though my gut tells me that I'll probably end up writing the documentation in my copious spare time, because I understand it better than anyone else in the OpenACS project at this point.
