Add events to clearing

1. These are the changes I mentioned in issue #3136, with examples in the doc.