improve javadoc and rename parameter