adding javadoc, and a small refactor