update docs, add example tests and fix bugs