added docs and tests and fixed bugs they uncovered