In order to make the doc generation for #476 working I had to fix some
errors in existing files. These cover

 - lines which are too long
 - incorrect indentation
 - invalid markup
 - missing javadoc