rewrite api doc for FormWidget and FormValueWidget, fixes #18363

cc @AdrianVasiliu 

Hopefully this addresses all the points you brought up.  You can add some inline comments if you see places for further clarification.
It does say that BUT a little before that it says:

> The change event fires when the value is committed, if that makes sense for the control, or else when the control loses focus.

So I think a lawyer would claim that the change event is mandatory (for all widgets)?