Javadoc generation ends with errors using JDK 8

[fredblain]

Using JDK 8, the Javadoc generation ends with multiple errors:

$ javadoc -J-version
 openjdk version "1.8.0_66"
 OpenJDK Runtime Environment (build 1.8.0_66-b17)
 OpenJDK 64-Bit Server VM (build 25.66-b17, mixed mode)

$ ant "-Dplatforms.JDK_1.8.home=/usr/lib/jvm/java-8-openjdk" javadoc
[...]
[javadoc] Constructing Javadoc information...
[javadoc] Standard Doclet version 1.8.0_66
[javadoc] Building tree for all the packages and classes...
[javadoc] /home/fblain/workspace/projects/questplusplus_dev/src/shef/mt/features/impl/Feature.java:41: warning: no @param for key
[javadoc]     public String getValue(Integer key) {
[javadoc]                   ^
[javadoc] /home/fblain/workspace/projects/questplusplus_dev/src/shef/mt/features/impl/Feature.java:41: warning: no @return
[javadoc]     public String getValue(Integer key) {
[javadoc]                   ^
[javadoc] /home/fblain/workspace/projects/questplusplus_dev/src/shef/mt/features/impl/Feature.java:87: warning: no @return
[javadoc]     public boolean isComputable() {
[javadoc]                    ^
[javadoc] /home/fblain/workspace/projects/questplusplus_dev/src/shef/mt/features/impl/gb/Feature2053.java:10: error: malformed HTML
[javadoc]  * percentage of other hypothesis with and edit distance to the centre <
[javadoc]                                                                        ^
[javadoc] /home/fblain/workspace/projects/questplusplus_dev/src/shef/mt/features/impl/gb/Feature2054.java:13: error: malformed HTML
[javadoc]  * percentage of other hypothesis with and edit distance to the centre <
[javadoc]                                                                        ^
[javadoc] /home/fblain/workspace/projects/questplusplus_dev/src/shef/mt/features/impl/Feature.java:15: error: malformed HTML
[javadoc]  * - the value attribute was transformed into a HashMap<Integer, String>;
[javadoc]                                                        ^
[...]
[javadoc] Building index for all the packages and classes...
[javadoc] Building index for all classes...
[javadoc] Generating /home/fblain/workspace/projects/questplusplus_dev/dist/javadoc/help-doc.html...
[javadoc] 65 errors
[javadoc] 78 warnings

This behaviour is due to doclint which has been added to Javadoc in its latest version. While with JDK 7 we could write anything that vaguely resembled HTML (plus additional tags like @date), doclint aims to get conforming W3C HTML 4.01 HTML... As a workaround, doclint can be deactivated by adding -Xdoclint:none to the Javadoc invocation:

$ javadoc -X
[...]
-Xdoclint                        Enable recommended checks for problems in javadoc comments
-Xdoclint:(all|none|[-]<group>) 
    Enable or disable specific checks for problems in javadoc comments,
    where <group> is one of accessibility, html, missing, reference, or syntax.
 [...]

thus, by changing nbproject/build-impl.xml (line 1243):

<javadoc additionalparam="-J-Dfile.encoding=${file.encoding} ${javadoc.additionalparam}" [...] >

to:

<javadoc additionalparam="-J-Dfile.encoding=${file.encoding} ${javadoc.additionalparam} -Xdoclint:none" [...] >

we get:

[javadoc] Building index for all the packages and classes...
[javadoc] Building index for all classes...
[javadoc] Generating /home/fblain/workspace/projects/questplusplus_dev/dist/javadoc/help-doc.html...
[javadoc] 20 warnings
[...]
BUILD SUCCESSFUL

Of course, this is a temporary fix till we clean all tags in order to be JDK 8 compliant.