bit of refactoring, and started adding examples to the docs