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.
@AdrianVasiliu sounds maybe more something like user guide doc? "how to write a widget extending FormValueWidget? I don't think the jsdoc should be cluttered with details, they should be left to the user guide.