updated docs: more example code

- all tested on Ubuntu 14.04 VM
- more explanations
- removed star-imports in last section