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

Also fix some warnings and other docu issues noted during work.
Merge pull request #7 from bradh/DDF-476

[DDF-476] Fix API documentation errors so that newer javadoc (JDK8) builds
Reviewed by: @mrmateo