[GRADLE-3099] Newline characters are filtered out from JavaDoc -header. Created: 03/Jun/14  Updated: 04/Aug/14  Resolved: 04/Aug/14

Status: Resolved
Project: Gradle
Affects Version/s: None
Fix Version/s: 2.1-rc-1

Type: Bug
Reporter: Gradle Forums Assignee: Szczepan Faber
Resolution: Fixed Votes: 0


 Description   

Newline characters are filtered out from JavaDoc -header. This breaks javascript and other code which I wish to inject into the JavaDoc, e.g. google analytics. See stackover flow for a more complete discussion of this problem. [1]http://stackoverflow.com/questions/23...

I have pasted Oleg Estekhin's explanation of the issue since it appears to be the most complete one provided so far:

----------------------- BEGIN PASTE -----------------------

I have an explanation, but i don't have a solution except for creating a new feature request in Gradle JIRA.

To generate a javadoc Gradle first generates the so-called argfile at build\tmp\javadocTaskName\javadoc.options that contains all individual options and than executes javadoc @full\path\to\build\tmp\javadocTaskName\javadoc.options command.

It is actually quite useful as you can debug the contents of that file by simply invoking javadoc @javadoc.options yourself from the command line.

It is possible to define multi-line values in the argfile by using the \ character at the end of each line inside the multi-line value.

The example header = "this is\na test which should fail" results in

-header 'this is
a test which should fail'

but we need to get

-header 'this is\
a test which should fail'

to tell javadoc that the value continues on the next line.

Now the problem is how to output that \ on each line.

The obvious attempt at header = "this is\\\na test which should fail" does not work, it will result in

-header 'this is\
a test which should fail'

And even Groovy multi-line or slashy strings will not work and will result in similar double back slashes.

Because Gradle just replaces all single backslashes in the option values. The JavadocOptionFileWriterContext.writeValue(String) method is the culprit, the replaceAll("\\\\", "\\\\\\\\") line in particular (a regex that matches single backslash and replaces it with double backslash ).

This escaping is required for backslashes inside a line, but it should not escape a single backslash followed by the new line character. My regex-fu is not strong enough to write such a pattern, but it is surely possible.

Or even better, the escaping mechanism inside that method should replace newline characters with a single backslash followed by the newline to hide all this stuff and allow users to declare multi-line javadoc options without the need to think or even know that feature.

I would appreciate if somebody can create an issue in Gradle tracker as i can't do so from my current location. This sentence should be replaced with the link to the issue so that people with similar problem can vote and track its progress.

----------------------- END PASTE -----------------------
----------------------------------------------------------------------------------------
[1] http://stackoverflow.com/questions/23763534/using-gradle-to-generate-javadoc-with-newline-characters-in-the-header



 Comments   
Comment by Perryn Fowler [ 03/Jun/14 ]

For clarity:

The issue is not that gradle strips 'newlines'(\n) but that it escapes backslashes () that are used as 'line continuations' in javadoc argfiles. Gradle should probably actually insert backslashes when it finds newlines.

Comment by Szczepan Faber [ 29/Jul/14 ]

I'm working on it but it won't work reliably on windows. I've tried plain javadoc command with options file that contains this:

-header 'this is\
a test which should fail'

It fails on windows. I've tried bunch of different combinations slashes, linebreaks, etc (and different windows+java combo) with no luck.

I'll go ahead and fix it. It will work for linux and mac neatly. For windows, it will work no worse than it used to.

Comment by Szczepan Faber [ 04/Aug/14 ]

This is fixed on non-windows environments. See the detailed description above. If there is a need for this feature on windows, please file a separate ticket.

Generated at Wed Jun 30 12:39:56 CDT 2021 using Jira 8.4.2#804003-sha1:d21414fc212e3af190e92c2d2ac41299b89402cf.