docs, tests and bug fixes