improve javadoc, fix typo #8