Improve javadocs wrt #628