refactoring: adding javadocs, cleaning code