Newline characters are filtered out from JavaDoc -header


(Peter Abeles) #1

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 -----------------------


(Perryn Fowler) #2

raised http://issues.gradle.org//browse/GRADLE-3099

The fastest way to get this addressed would be to submit a pull request with a patch. It should be pretty easy - would you be interested in helping out?

cheers Perryn

PS out of interest, how does not having newlines break your script? It seems strange to me since newlines are not significant in JS or HTML??


(Peter Abeles) #3

I’m not a web developer so I can’t really say why it breaks JS or HTML. The very first thing I tried was stripping out ‘\n’ and that broke it. When I messed with the generated HTML directly adding them back in fixed it.

I’ll get back to you about the patch after I’ve had a chance to look at Gradle’s source code. Implenenting Oleg’s suggestion sounds straight forward enough…


(Perryn Fowler) #4

cool - you will want to look at org.gradle.external.javadoc.internal.JavadocOptionFileWriterContext.java

let me know if you need any help