ready for Pkg.test

moved test examples from `test/` to `examples/`
updated inline documentation