javadoc clarifications