使用Gradle在“头文件”中用换行符生成JavaDoc。 [英] Using Gradle to generate JavaDoc with newline characters in the "header"

问题描述

更新：在Gradle论坛上发布了一篇文章。请为此问题加分，以便更多关注 http://gsfn.us/t/4jedo

我正在从主要的Ant构建环境转换到Gradle环境。一个棘手的问题是将Google Analytics和Adsense代码注入到JavaDoc中。这是通过将Java脚本代码放入页眉或底部面板来完成的。对于我目前正在做的一个示例，请看这个问题 CDATA 。

Gradle的问题在于它无法处理要插入的字符串中的换行符。如果您过滤掉了这些字符，则会破坏脚本。这是一个代码sniplet：

pre $ task alljavadoc（type：Javadoc）{
source = javadocProjects.collect {project（它）.sourceSets.main.allJava}
classpath = files（javadocProjects.collect {project（it）.sourceSets.main.compileClasspath}）
destinationDir = file（$ {buildDir} / docs / javadoc ）
configure（options）{
header =这是应该失败的测试
}
}


关键部分是header =。如果你删除'\ n'字符，它将工作得很好。否则，对Gradle生成的javadoc的调用将会失败，并显示以下错误：

 成功启动进程'command'/ opt / jdk / jdk1.7.0_21 / bin / javadoc''
 javadoc：错误 - 非法包名：
 javadoc：警告 - 包a没有源文件
 javadoc：警告 - 无源文件为包测试
 javadoc：警告 - 没有包的源文件
 javadoc：warning  - 包没有源文件应该
 javadoc：warning  - 包没有源文件失败
  

下面是我希望包含的真正的java脚本。请注意，我无法通过删除新行字符来破解它，因为这会破坏脚本。

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

作为一项完整性检查，我还将一个带有新行字符的字符串直接传递给javadoc （manual） on命令行，它工作得很好。

  javadoc foo.java -header这是一个测试
等等是这个
  

输出HTML：

 < div class =aboutLanguage>< em>这是一个测试
，所以这是< / em>< / div> 
< / div> 
  

解决方案

我有一个解释，但我没有一个解决方案，除了在Gradle JIRA中创建一个新的功能请求。

生成一个javadoc Gradle首先生成所谓的 argfile at build\tmp\javadocTaskName\javadoc .options 包含所有单个选项并执行 javadoc @ full \path\to\build\tmp\javadocTaskName\javadoc.options
$ b

它实际上非常有用，因为您只需调用 javadoc @ javadoc.options 即可调试该文件的内容。
$ b

可以通过使用 \ <>来定义argfile中的多行值。 / code>字符在多行值内的每行末尾。

header =this is\\\
a test which should fail results in

  -header'这是
a测试应该失败'
  

但我们需要得到

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

告诉javadoc这个值继续在下一行。

现在问题是如何在每一行输出 \ 。

明显的尝试在头部=这是应该失败的测试不起作用，它会导致

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

<即使Groovy多行或斜杠字符串也不起作用，并且会导致类似的双斜杠。

因为Gradle只是替换选项值中的所有单反斜杠。 JavadocOptionFileWriterContext.writeValue（String）方法是罪魁祸首， replaceAll（\\\\，\\\\\\ \\\\）特别是一行（匹配单个反斜杠的正则表达式，并用双反斜杠替换它）。

这个转义是行内反斜杠所必需的，但它不应该跳过一个反斜杠，然后是新的行字符。我的正则表达式不足以编写这样的模式，但它肯定是可能的。

或者更好的是，该方法中的转义机制应该将换行符替换为一个反斜线后跟一个新行来隐藏所有这些东西，并允许用户声明多行的javadoc选项，而不需要思考甚至不需要知道该功能。

我会欣赏是否有人可以在Gradle追踪器中创建问题，因为我无法从当前位置执行此操作。应该用这个问题的链接来替换这个句子，以便有类似问题的人可以投票并跟踪它的进度。

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>

解决方案

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.

这篇关于使用Gradle在“头文件”中用换行符生成JavaDoc。的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！