minor refactoring (encapsulation) and ScalaDoc