add scaladoc and refactor method name