Improve ScalaDoc/JavaDoc, see #3152

This pull request will consist of several commits to break down this huge task in manageable steps.