loads of javadoc updates

Notice that I added:

- some minimal text where there was none (perhaps that is of some value, but perhaps someone disagrees with some specific addition) 
- text must be above `@author` tags, otherwise text gets inserted into the `author` description
- loads of `// XXX no javadoc` markers. Honestly, I am afraid of documention some things and only worsening it by adding wrong information