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.
I don't know for sure, and I was hoping you know it, such that the doc clarifies it. Now, assuming "change" is mandatory as your "lawyer" claims, does the same hold for "input"? Again, StarRating isn't firing it; either this is wrong, or "input" isn't mandatory. And if at least one of the events isn't mandatory, we're back at my original (small) remark about the doc wording (saying that subclasses  "should call `handleOnChange()` and `handleOnInput()`").