minimal code refactor and javadoc