Partly undo the configuration performed on a task by a plugin

Help/Discuss
1

I needed to add a plugin that adds -Xdoclint:none to all Javadoc tasks1 . However, this interferes with my configuration of Javadoc tasks, overriding my -Xdoclint:all,-missing.

How can I undo this configuration done by the plugin?

1: Plugin adds "-Xdoclint:none -quiet" to all javadoc task, interfering with user configurations · Issue #1132 · vanniktech/gradle-maven-publish-plugin · GitHub

2

The problem is, that this plugin is very badly implemented.

For example it does this configuration within afterEvaluate which any plugin should avoid under almost all conditions and for almost any cost and thus comes after your configuration.

It’s also not nice that the plugin just assumes the used doclet supports this option, or the html5 option just because Java 9+ is used.

Unfortunately, there is a bug in Gradle it seems so that using afterEvaluate yourself would also not help here and even if the plugin would not use afterEvaluate it would not help, because JavadocOptionFile uses LinkedHashMaps to preserve the options ordering, but in JavadocOptionFile#stringifyExtraOptionsToMap returns a normal HashMap which makes the order random and even if your option is added later still might or might not provide the proper ordering.

So I think the only option you have to mitigate the problem besides fixing or monkey-patching that plugin is, to use a custom doclet that filters out the unwanted option and then forwards to the standard doclet.

3

Ah, no, looking further, there is a way.
If you add a string option with value null (or use the overload with only the option name), the option is unset.
So indeed you can work-around the plugin behavior by doing

addStringOption("Xdoclint:none")
addStringOption("Xdoclint:all,-missing", "-quiet")

but as the plugin still is using the evil afterEvaluate you also have to use it to mitigate the behavior.
So this will mitigate the problem:

tasks.javadoc {
    (options as StandardJavadocDocletOptions).addStringOption("Xdoclint:all,-missing", "-quiet")
}
afterEvaluate {
    tasks.javadoc {
        (options as StandardJavadocDocletOptions).addStringOption("Xdoclint:none")
    }
}
1 Like
4

Besides that you probably did not want to use

addStringOption("Xdoclint:all,-missing", "-quiet")

but

addBooleanOption("Xdoclint:all,-missing", true)
5

Thanks, this does the trick. :slight_smile:

That said, I find it very surprising that addStringOption("Xdoclint:none") actually unsets an option. This seems like an API wart (and not really documented).

That’s worrisome to hear given that it appears to be the “go-to plugin” for publications via the new Maven Central API.

6

That’s worrisome to hear given that it appears to be the “go-to plugin” for publications via the new Maven Central API.

Well, I just had a very quick look to investigate this and immediately found afterEvaluate and plugins.hasPlugin which both are discouraged bad practices. No idea what other bad practices that plugin follows. :man_shrugging:

That said, I find it very surprising that addStringOption("Xdoclint:none") actually unsets an option. This seems like an API wart (and [not really documented].

Yes, I fully agree.
There is for example Javadoc options addStringOption("foo") does not work as expected. · Issue #2354 · gradle/gradle · GitHub that complains about exactly this and should finally lead to some doc improvements at least.

addBooleanOption("foo") is a short-hand for addBooleanOption("foo", false) and a false boolean option is not given to JavaDoc.
addStringOption("foo") is a short-hand for addStringOption("foo", null) and a null string option is not given to JavaDoc.

These are necessary to unset options like in cases like here.

addStringOption is for options where you have a key and a value that are given as two arguments.
addBooleanOption is for options that should be supplied or not as one option, so things like -Xdoclint:all,-missing are considered a boolean option.

7

Actually, add...Option also returns an option object on which the value can be set, so addStringOption("foo") can be used to unset the option, but it could also be used like addStringOption("foo").value = "bar" to supply -foo bar as arguments.

8

I submitted a PR that adds the missing JavaDoc that should clear up the API usage in that part at Add JavaDoc for CoreJavadocOptions option methods (#2354) by Vampire · Pull Request #34833 · gradle/gradle · GitHub

9

And here the PR that will maintain the option order if it gets incorporated: Preserve the order of extra JavaDoc options by Vampire · Pull Request #34834 · gradle/gradle · GitHub

Actually, I looked at only one of two places, the place I mentioned was just for up-to-date checks. The actual JavaDoc options were sorted by option name which caused your option to be sorted above the option from the plugin.