Undocumented change in Javadocs in Java 8 u121

classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|

Undocumented change in Javadocs in Java 8 u121

Uwe Schindler-4
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
[hidden email]
ASF Member, Apache Lucene PMC / Committer
Bremen, Germany
http://lucene.apache.org/


Reply | Threaded
Open this post in threaded view
|

Re: Undocumented change in Javadocs in Java 8 u121

Michel Trudeau
Uwe,

Thanks for reporting the issue.  The new command line argument should have been documented in the release notes.   We are fixing this.

--
Thanks,
Michel



January 22, 2017 at 4:07 AM
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
[hidden email]
ASF Member, Apache Lucene PMC / Committer
Bremen, Germany
http://lucene.apache.org/



Reply | Threaded
Open this post in threaded view
|

Re: Undocumented change in Javadocs in Java 8 u121

Michel Trudeau
Updated release notes for 8u121.

http://www.oracle.com/technetwork/java/javase/8u121-relnotes-3315208.html

--
--Michel



January 24, 2017 at 5:44 PM via Postbox
Uwe,

Thanks for reporting the issue.  The new command line argument should have been documented in the release notes.   We are fixing this.




January 22, 2017 at 4:07 AM via Postbox
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
[hidden email]
ASF Member, Apache Lucene PMC / Committer
Bremen, Germany
http://lucene.apache.org/



Reply | Threaded
Open this post in threaded view
|

Re: Undocumented change in Javadocs in Java 8 u121

Uwe Schindler-4
Thanks!

If I understand correctly, it adds a warning for javadoc code comments that contain JS, but fails if the top or bottom parameter contains JS.

Uwe

Am 26. Januar 2017 23:10:21 MEZ schrieb Michel Trudeau <[hidden email]>:
Updated release notes for 8u121.

http://www.oracle.com/technetwork/java/javase/8u121-relnotes-3315208.html

--
--Michel



January 24, 2017 at 5:44 PM via Postbox
Uwe,

Thanks for reporting the issue.  The new command line argument should have been documented in the release notes.   We are fixing this.




January 22, 2017 at 4:07 AM via Postbox
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
[hidden email]
ASF Member, Apache Lucene PMC / Committer
Bremen, Germany
http://lucene.apache.org/



Reply | Threaded
Open this post in threaded view
|

Re: Undocumented change in Javadocs in Java 8 u121

Jonathan Gibbons
Uwe,

Unfortunately, the release note is incorrect and needs to be updated.

All uses of JavaScript will be rejected, unless the enabling option is specified. This applies equally to JavaScript found in documentation comments and any command-line options used to specify fragments of HTML to be included in the generated documentation. It applies to uses of the "<script>...</script>" tag and to event handlers, such as "onclick", "onload", etc (See http://www.w3schools.com/jsref/dom_obj_event.asp )

-- Jon

On 01/27/2017 12:20 AM, Uwe Schindler wrote:
Thanks!

If I understand correctly, it adds a warning for javadoc code comments that contain JS, but fails if the top or bottom parameter contains JS.

Uwe

Am 26. Januar 2017 23:10:21 MEZ schrieb Michel Trudeau [hidden email]:
Updated release notes for 8u121.

http://www.oracle.com/technetwork/java/javase/8u121-relnotes-3315208.html

--
--Michel



January 24, 2017 at 5:44 PM via Postbox
Uwe,

Thanks for reporting the issue.  The new command line argument should have been documented in the release notes.   We are fixing this.




January 22, 2017 at 4:07 AM via Postbox
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
[hidden email]
ASF Member, Apache Lucene PMC / Committer
Bremen, Germany
http://lucene.apache.org/