update documentation for onconfirm to other words

I find the first draft very difficult to understand. Maybe this (and the examples) helps to clarify
Merge pull request #692 from pscheit/patch-2

update documentation for onconfirm to other words