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.
(Minor) Wondering whether we didn't standardize on using the active form when documenting methods, so "Set" => "Sets", "fire" => "fires".