some more comments/javadoc/basic refactoring

Same kind of stuff as the previous pull request.