[DS-3154] Maven release process fails when using Java 8 because of Javadocs errors

[dspace-bot]

Imported from JIRA [DS-3154] created by tdonohue

Currently, if you attempt to run mvn release:perform using Java 8, the Maven process will fail almost immediately because of Javadocs errors.

This is because DocLint was added in Java 8: http://openjdk.java.net/jeps/172

See also: http://stackoverflow.com/questions/15886209/maven-is-not-working-in-java-8-when-javadoc-tags-are-incomplete

Also, this blog post has a list of invalid JavaDocs with Java 8 will now complain about: http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html

While it is possible to disable DocLint checks, it is NOT recommended (obviously). The better route would be to cleanup our Javadocs errors (warnings are OK) so that Java 8 releases will succeed.

You can also see these errors by simply running mvn javadoc:aggregate using Java 8, as this attempts to generate Javadocs for all our modules.

[dspace-bot]

Is related to: DS-3308

[dspace-bot]

Addressed by / Fixed by: DS-3384

[dspace-bot]

tdonohue said:

For 6.0, we may be forced to simply turn off doclint (see link in description describing how to do that). We can then create a new ticket(s) to accomplish the other known Javadocs cleanup in future releases.

[dspace-bot]

tdonohue said:

PR created to disable doclint for 6.0: #1467

[dspace-bot]

helix84 said:

PR to fix JavaDoc: #1484

[dspace-bot]

tdonohue said:

The PR from Ivan Masár has been merged.

Just as a note, while Ivan Masár's PR helps things, we still have a very large number of javadocs errors/warnings in our modules. Here's what counts are reported when running mvn javadoc:javadoc (using Java 8) from each of our module subdirectories. Keep in mind, that 100 is the maximum number of issues ever reported, so a tally of 100 really means >=100.

• dspace: 0 errors, 0 warnings
• dspace-api: 51 errors, >=100 warnings
• dspace-jspui: 37 errors, >=100 warnings
• dspace-oai: 67 errors, 0 warnings
• dspace-rdf: 0 errors, 0 warnings
• dspace-rest: 5 errors, >=100 warnings
• dspace-services: 0 errors, 0 warnings
• dspace-solr: 0 errors, 0 warnings
• dspace-sword: 6 errors, >=100 warnings
• dspace-swordv2: 2 errors, >=100 warnings
• dspace-xmlui: 0 errors, 5 warnings
• dspace-xmlui-mirage2: (no java code)

Unfortunately, from my testing, it seems like you need to correct everything that javadoc returns as either an "error" or a "warning" before Java 8 will succeed with 'doclint' enabled. So, unfortunately, we still have a lot of work to do.

[dspace-bot]

pbecker said:

In the developer meeting on September 7 2016 this was discussed (http://irclogs.duraspace.org/index.php?date=2016-09-07). I created the release of DSpace 6 RC3 using Java 7 to avoid any of the problems described within this ticket. That mean the existence of DSpace 6 RC3 is no testimony regarding if this issues is solved or not. I leave this ticket closed as DS-3308 is a good follow up and this ticket can be reopened anytime we run into the same problem again.

[dspace-bot]

helix84 said:

Just a note: the doclint checks have been disabled in OpenJDK 8 in Debian, that's why I couldn't see the bulk of the errors and warnings. Doclint in Oracle JDK 8 shows the errors.