added scaladoc
added explicit return types
added parameter documentation