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) "end-user" => "end user" ? (consistently with occurrence at line 47 below, and with http://www.merriam-webster.com/dictionary/end-user).