mostly finish scaladoc; introduce result type to simplify value fetching