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 guess when I asked for more explanation about `value` I didn't see yet the added paragraph in the doc of the FormWidget.value. That said, the doc of FormWidget.value starts with "Corresponds to the native HTML `<input>` element's attribute.", and this main sentence fits rather the case of the FormValueWidget subclass, isn't it? Maybe FormValueWidget could override the doc of the value property, such that there is a version which fits for each:
* FormWidget.value:  "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 to take the example of a checkbox widget."
* FormValueWidget.value: `value` can be set by the end user (via mouse, keyboard, or touch).

The combined description in the paragraph you quoted could be placed in the doc of FormWidget, while clarifying which of FormWidget vs FormValueWidget holds for each case, say:

"For widget extending `FormValueWidgetè, that is most widgets, `value` can be set by the end user (via mouse, keyboard, or touch). For widgets extending `FormWidget` directly, 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."