added two new functions; clarified some of the language in the documentation