Improve mapping related scaladoc

review by @szeiger and @wsargent