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:
You can use the options.addStringOption() method in a Javadoc configuration closure.
Yes, I see it, but getting this to actually work is not going to be obvious at all.
If I just do this:
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.
addStringOption('something') as no effect on the javadoc properties, while
addStringOption('key', 'value') works as expected. Command line options become
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.
// without the -quiet option, the build fails
I just tested on a small project with one class with badly designed javadoc:
- br tags
- Text making use of
> such as
@param argument name
@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.
If it has no value, it is a boolean option.
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)
worked for me.
addStringOption, but I said
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
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"))}
Still, don’t abuse
in kotlin syntax for build.gradle.kts
this as StandardJavadocDocletOptions
(options as StandardJavadocDocletOptions).addBooleanOption("Xdoclint:none", true)
(options as StandardJavadocDocletOptions).addStringOption("Xmaxwarns", "1")