document public methods and refactor