Added --allow-script-in-comments to javadoc config

[nikarh]

Since Java 8u121, JavaScript is disabled in JavaDoc's by default (http://www.oracle.com/technetwork/java/javase/8u121-relnotes-3315208.html), failing build. To fix this JavaScript should be enabled explicitly with a flag --allow-script-in-comments.

[lutovich]

Hi @nikarh!

Thanks for the contribution.

We build the driver only with Java 7 and run tests with both Java 7 and 8. So this javadoc problem is not an issue at this point. It also turns out that just adding allow-script-in-comments option will fail javadoc generation on all JDK versions prior to 1.8u121. Pull request build that uses Java 7u95 failed with this error:

Failed to execute goal org.apache.maven.plugins:maven-javadoc-plugin:2.9.1:jar (attach-javadocs) on project neo4j-java-driver: MavenReportException: Error while creating archive: 
Exit code: 1 - javadoc: error - invalid flag: --allow-script-in-comments

Command line was: /usr/lib/jvm/java-7-openjdk-amd64/jre/../bin/javadoc @options @packages

See these two issues for more details:

• Fix JavaDoc generation on recent JDK 8 builds mockito/mockito#934 (has an example of conditional adding of allow-script-in-comments param)
• https://issues.apache.org/jira/browse/LUCENE-7651

Not sure there is a good way to add --allow-script-in-comments to Maven javadoc plugin conditionally based on the JDK version. So suggest we add it to the pom like you did but commented out with a comment saying why it might be needed in future.

What do you think?

[nikarh]

Hi, thank you for your reply.
I agree with leaving it in a comment for now. I will edit my pr now

[lutovich]

@nikarh I think -- needs to be escaped in XML comments. Build failed with error:

Non-parseable POM: in comment after two dashes (--) next character must be > not a (position: END_TAG seen ...<!--<additionalparam>--a... @139:35)  @ line 139, column 35

[nikarh]

@lutovich Thanks, this was somewhat unexpected. Would escaping it as <!--<additionalparam>&#45;&#45;allow-script-in-comments</additionalparam>--> be appropriate?
I believe in most IDE's commenting this line out would unescape it properly.

[lutovich]

@nikarh yeah, this escaping looks a bit strange. Unescaping works in IntelliJ. Thanks again for the contribution!