Using Gradle to generate JavaDoc with newline characters in the “header”

问题

UPDATE: Made a posting on the Gradle forum. Please star this issue so that it gets more attention http://gsfn.us/t/4jedo

I'm in the process of transitioning from a primarily Ant build environment into a Gradle one. One sticking point is injecting Google Analytics and Adsense code into the JavaDoc. This is done by putting java script code into the header or bottom panels. For an example of what I'm currently doing, look at this question CDATA.

The problem with Gradle is that it can't handle newline characters in the string which is to be inserted. If you filter out those characters you break the script. Here is a code sniplet:

task alljavadoc(type: Javadoc) {
    source = javadocProjects.collect { project(it).sourceSets.main.allJava }
    classpath = files(javadocProjects.collect { project(it).sourceSets.main.compileClasspath })
    destinationDir = file("${buildDir}/docs/javadoc")
    configure(options) {
        header = "this is\na test which should fail"
    }
}

The critical part is "header =". If you remove the '\n' character it will work just fine. Otherwise the call to javadoc, which Gradle makes, will fail with the following error:

Successfully started process 'command '/opt/jdk/jdk1.7.0_21/bin/javadoc''
javadoc: error - Illegal package name: ""
javadoc: warning - No source files for package a
javadoc: warning - No source files for package test
javadoc: warning - No source files for package which
javadoc: warning - No source files for package should
javadoc: warning - No source files for package fail

The actual java script that I wish to include is below. Note that I can't hack it by removing new line characters since that will break the script.

<script async src="//pagead2.googlesyndication.com/pagead/js/adsbygoogle.js"></script>
<!-- banner -->
<ins class="adsbygoogle"
     style="display:inline-block;width:468px;height:60px"
     data-ad-client="ca-pub-xxxxxxxxxxxxxxxxx"
     data-ad-slot="xxxxxxxxx"></ins>
<script>
(adsbygoogle = window.adsbygoogle || []).push({});
</script>

As a sanity check I also passed in a string with new line characters directly to javadoc (manual) on the command line and it works just fine.

javadoc foo.java -header "This is a test
and so is this"

The output HTML:

<div class="aboutLanguage"><em>This is a test
and so is this</em></div>
</div>

回答1:

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.

回答2:

I tried to implement it in Gradle but I couldn't get it to work reliably on windows. If the options file has this:

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

It works nicely on linux/mac but fails on windows (tried on win7/java7 and some other windows+java6). I've tried with vanilla javadoc executable (without Gradle).

I'll get the fix into Gradle and it will work out of the box for linux/mac but not quite for windows. If you want to help out with windows support catch us at http://issues.gradle.org/browse/GRADLE-3099

来源：https://stackoverflow.com/questions/23763534/using-gradle-to-generate-javadoc-with-newline-characters-in-the-header

标签

java

google-analytics

gradle

javadoc