more docs and make variable names consistent