How to send "-X" option to javadoc?

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>

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

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.

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

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

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

You used addStringOption, but I said addBooleanOption :wink:

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

Yep, that was exactly my point :slight_smile:

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.

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