improving javadocs