cleaned up some weirdness in README. added comments and fixed random docstring inconsistencies