added documentation, examples, and test cases