rewrite api doc for FormWidget and FormValueWidget, fixes #329

cc @AdrianVasiliu 

Hopefully this addresses all the points you brought up.  You can add some inline comments if you see places for further clarification.
OK, fixed in e8944f96e2f80732193927b4fc812f65cc20c26e.

Looks like you wrote your comments from the "Files changed" tab?  That means the get "erased" when I do a new commit.   Using the "Commits" tab is better.