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.
@cjolif - sure, it's just that for now the user guide doesn't say more (it actually says less than the API doc after the changes in this PR). But you're right, further details can be left for a future version of the user guide.