javadoc; clarifications; simplifications