rewrite api doc for FormWidget and FormValueWidget, fixes #329

cc @AdrianVasiliu 

Hopefully this addresses all the points you brought up.  You can add some inline comments if you see places for further clarification.
> I would propose to keep this slightly amended variant of your initial prose:
> "FormValueWidget shouldn't be used for widgets that extend or embed native form elements such as `<select>`...

I'm not going to write that because then you or someone else will later complain about how it's inaccurate for a FormWidget / FormValueWidget with an embedded `<select>` where the `<select>`'s "input" and "change" events are suppressed.   For example, a ColorPicker widget with an embedded `<select>` for RGB vs. some other mode.