more comments from #2849
 - javadoc
 - typo