minor refactoring + some more javadocs