implementing the new extend() mechanism

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