more Javadoc/added params in too