[DDF-476] Fix API documentation errors so that newer javadoc (JDK8) will build

Also fix some warnings and other docu issues noted during work.