more JavaDoc, some method refactoring