Use Gradle's task configuration avoidance APIs in the main reference docs

[larsgrefer]

see #29762
see https://docs.gradle.org/7.0/userguide/task_configuration_avoidance.html

[wilkinsona]

Thanks, @larsgrefer. I've left a couple of comments for your consideration when you have a minute.

[wilkinsona]

I think will eagerly create the processResources task.

[larsgrefer]

This will only create the processResources task when the closure is executed, which in turn only happens when compileJava is being created/configured. In this case, processResources would have to be created anyway.

[wilkinsona]

I wonder if that is that the case 100% of the time.

Regardless, this is an example of the increased complexity of task configuration avoidance — you need to be more aware of the relationships between tasks. According to Gradle’s own docs, you also need to consider where the task was created.

In this case processResources is defined by another plugin, but so is compileJava. That makes Gradle’s guidance a little unclear to me.

My feeling is that consistently using tasks.named in a situation such as this reduces cognitive load. You don’t need to think about where a task has come from or their existing relationships and things will just work (I think).

[larsgrefer]

In my tests it did not make a difference if processResources is used lazily or directly (inside the lazily evaluated compileJava closure). The nearest match in the Gradle docs I could find is this:

tasks.register("someTask")

tasks.register("anEagerTask") {
    dependsOn someTask
}

Here someTask is referenced directly inside the lazy configuration closure of anEagerTask.

That being said, I agree that just always using tasks.named makes things more consistent.

[wilkinsona]

I don't think the task's type is needed here.

[larsgrefer]

Yes, it would work without the type.

I've added the explicit type declaration to give the IDE a chance to resolve what expand refers to, but at least for IntelliJ IDEA this does not seem to be sufficient.

For proper auto-completion in IntelliJ IDEA we'd need this:

tasks.named('processResources', Copy) {
    it.expand(project.properties)
}

If we don't care about IDE support, this would be enough:

tasks.named('processResources') {
    expand(project.properties)
}

[wilkinsona]

Thanks. Given that it’s unrelated to configuration avoidance, please revert this part of the changes.

[larsgrefer]

I've updated the PR based on your comments.

[wilkinsona]

Thanks very much, @larsgrefer.