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

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