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 guess "input" is mandatory too, according to this paragraph:

> For input elements without a defined activation behavior, but to which these events apply, and for which the user interface involves an explicit commit action but no intermediate manipulation, then any time the user commits a change to the element's value, the user agent must queue a task to first fire a simple event that bubbles named `input` at the `input` element, and then fire a simple event that bubbles named `change` at the `input` element.