javadoc improvement wrt #325