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.
I'm really not sure how I can give more explanation.   I already wrote a paragraph about it:

>  For most widgets, `value` can be set by the end user (via mouse, keyboard, or touch), but for widgets
>  like checkboxes, the value is set programatically when the widget is created, and the end user
>  merely changes the widget's state, i.e. the checked property.

If you have some suggested text, let me know.