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. http://stackoverflow.com/questions/23763534/using-gradle-to-generate-javadoc-with-newline-characters-in-the-header
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 -----------------------