javadoc improvements wrt #603