more javadoc and minor refactorings