remove some irrelevant (and confusing) hackery
cleanup and add some docs