How to send "-X" option to javadoc?

Help/Discuss
1

I’m porting a project from Maven to Gradle. The javadoc plugin needs an “-X” option passed to it. I don’t see how I can do that with the Gradle javadoc task.

The original reference in the Maven pom looks like this:

<additionalparam>-Xdoclint:none</additionalparam>

2

Hi,

You can use the options.addStringOption() method in a Javadoc configuration closure.
See http://blog.joda.org/2014/02/turning-off-doclint-in-jdk-8-javadoc.html

3

Yes, I see it, but getting this to actually work is not going to be obvious at all.

If I just do this:

addStringOption(‘Xdoclint:none’)

It doesn’t get added to the command line. I verified this with the resulting “javadoc.options” file. I then tried doing the following:

addStringOption(‘Xdoclint:none’).value = “”

This gets close, as it at least puts the option on the command line, but it actually gives the parameter a value, the empty string, so javadoc thinks that’s a package name, and barfs.

I also tried changing the empty string to “null”, but that does the same as the first, doesn’t put it on the command line.

4

The addStringOption('something') as no effect on the javadoc properties, while addStringOption('key', 'value') works as expected. Command line options become -key value.

There was apparently an issue with non valued javadoc options, cause there is commit reverting it: https://github.com/gradle/gradle/commit/a7da520ac4025cc38a47672de570a87990f9bca1

Now, to add a -X option, we have to trick Gradle to make it accept our option as a key/value. But as you experienced yourself, the empty string will lead to an error. That’s why people add -quiet, this is a rather harmless option for the javadoc binary.

javadoc {
    // without the -quiet option, the build fails
    options.addStringOption('Xdoclint:none', '-quiet')
}

I just tested on a small project with one class with badly designed javadoc:

  • br tags <br/>
  • Text making use of < and > such as Collection<Foo>
  • unknown @param argument name
  • undefined @param argument description

with Maven and Gradle. Both break the build without appropriate configuration. Both manage to generate something with the Xdoclint:none set. Resulting html is almost the same in both case with two differences only: Maven generates link to the Java public apidoc by default, and there is an additional link in the navigation bar: “use” linking to class-use folder.

2 Likes
5

If it has no value, it is a boolean option.
Just do addBooleanOption 'Xdoclint:none', true and it works fine.

1 Like
6

@Vampire that doesn’t seem to work for me, I get the following error:

No signature of method: org.gradle.external.javadoc.StandardJavadocDocletOptions.addStringOption() is applicable for argument types: (String, Boolean) values: [Xdoclint:none, true]
  Possible solutions: addStringOption(java.lang.String), addStringOption(java.lang.String, java.lang.String), addStringsOption(java.lang.String), addStringsOption(java.lang.String, java.lang.String)

Changing to

javadoc {
    options.addStringOption('Xdoclint:none', '-quiet')
}

worked for me.

7

You used addStringOption, but I said addBooleanOption :wink:

8

Aha! Thanks for the correction. I like addBooleanOption better, since it doesn’t require me to also add -quiet or similar.

9

Yep, that was exactly my point :slight_smile:

10

Is there a way to specify multiple options with the same name?

I’m trying to pass multiple -tag arguments to javadoc, but Gradle is throwing away all of them except the last one.

I really wish the Javadoc task would let us configure the ExecSpec, then we’d have full control over all this.

1 Like
11

addMultilineStringsOption("tag").setValue(listOf("a", "b", "c"))}

13

Still, don’t abuse addStringOption, use addBooleanOption

1 Like
14

in kotlin syntax for build.gradle.kts

tasks.withType<Javadoc> {
    options {
        this as StandardJavadocDocletOptions
        addBooleanOption("Xdoclint:none", true)
        addStringOption("Xmaxwarns", "1")
    }
}

tasks.withType<Javadoc> {
    (options as StandardJavadocDocletOptions).addBooleanOption("Xdoclint:none", true)
    (options as StandardJavadocDocletOptions).addStringOption("Xmaxwarns", "1")
}
2 Likes