adding doc, refactoring tests, and two new functions