update javadoc to be consistent with recent refactorings