implementing the new extend() mechanism

* [x] docs
* [x] examples
* [ ] test