added docs and renamed a couple of methods