Undocumented change in Javadocs in Java 8 u121

[Uwe Schindler]

Hi,

after updating our Jenkins server to Java 8 update 121, we noticed the folliwng error message while building Javadocs:

[javadoc] Constructing Javadoc information...
[javadoc] javadoc: error - Argument for -bottom contains JavaScript.
[javadoc] Use --allow-script-in-comments to allow use of JavaScript.
[javadoc] 1 error

This did not happen with update 112 that was used before.

If fact, we use Javascript there (inside -bottom), but its use is legitimate and I think many other projects will be affected by this, too! We include Google's Code Prettify Javascript files into the Javadocs, so we get syntax highlighting for tons of examples in Apache Lucene's Javadocs. This now breaks unexcpectedly by this change. It is important to have source code examples correctly highlighted in Javadocs for readability. Maybe you should think about adding this to Java 9, too!

We have a fix for this already: As we inject CSS for in prettify.css already into the stylesheet.css file after the javadocs run, the trick is to also inject the prettify.js code into the script.js file after the run, this would be the better approach. See https://issues.apache.org/jira/browse/LUCENE-7651 for more info.

Nevertheless, this change is completely undocumented:
- No release note mentions
- There is no documentation anywhere on the web about "--allow-script-in-comments" (and what does this have to do with comments????)

Is this a bug because it was introduced into a minor update? I suspect a backport that introcuced this by accident. I would be fine to have this in Java 9, but suddenly adding this without any documentation into a minor feature release is a no-go. I am sure, we are not the only project affected by this.

Unfortunately, the above fix (https://issues.apache.org/jira/browse/LUCENE-7651) did not go into our latest Lucene/Solr release. 6.4.0 will come out on Monday, release votes are already passed. Now it is impossible to build it with Java 8 update 121 - not good!

Uwe

-----
Uwe Schindler
uschindler at apache.org 
ASF Member, Apache Lucene PMC / Committer
Bremen, Germany
http://lucene.apache.org/