ENGINE-1825: improve javadoc