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.
> What isn't very clear here (to me) is whether widget.value == widget.input.value per contract.

Understood, I will clarify.

> Maybe not, since the value attribute of the input element is only the initial value (per HTML spec),

Well, the FormValueWidget's `value` is serialized to the `<input>`'s value *property*.