TaskCollection.matching needs more elaborate description regarding task-configuration avoidance

[Vampire]

Issue type

Wrong or misleading information

Problem description

Up to (including) 7.2, the task configuration avoidance documentation stated:

Instead of: TaskCollection.matching(groovy.lang.Closure)
Use: OK
This is OK to use because it does not require tasks to be created immediately.

For 7.3 this was changed in #17885 to

Instead of: TaskCollection.matching(groovy.lang.Closure)
Use: OK, with issues.
matching(Spec) requires all tasks to be created, so try to limit the impact by restricting the type of task, like withType(java.lang.Class).matching(Spec).

Besides the discrepancy of argument types in left and right column, while it affects both overloads the same,
both variants are misleading and it needs more elaborate description or instructions.

If you put the following into an empty build script (DSL doesn't matter):

tasks.matching {
    println("matching ${it.name}")
    it.enabled == true
}.configureEach { println("configure task $name conditionally") }
tasks.configureEach { println("configure task $name") }

tasks.register("foo") {
    dependsOn(tasks.matching {
        println("matching ${it.name} for dependsOn")
        it.enabled == false
    })
}

Then execute gw help, the output is

matching help
configure task help conditionally
configure task help

If you without further change execute gw :foo the output is

matching foo
configure task foo conditionally
configure task foo
matching help
configure task help conditionally
configure task help
matching projects
configure task projects conditionally
configure task projects
matching tasks
configure task tasks conditionally
configure task tasks
matching properties
configure task properties conditionally
configure task properties
matching dependencyInsight
configure task dependencyInsight conditionally
configure task dependencyInsight
matching dependencies
configure task dependencies conditionally
configure task dependencies
matching buildEnvironment
configure task buildEnvironment conditionally
configure task buildEnvironment
matching components
configure task components conditionally
configure task components
matching model
configure task model conditionally
configure task model
matching dependentComponents
configure task dependentComponents conditionally
configure task dependentComponents
matching outgoingVariants
configure task outgoingVariants conditionally
configure task outgoingVariants
matching resolvableConfigurations
configure task resolvableConfigurations conditionally
configure task resolvableConfigurations
matching javaToolchains
configure task javaToolchains conditionally
configure task javaToolchains
matching prepareKotlinBuildScriptModel
configure task prepareKotlinBuildScriptModel conditionally
configure task prepareKotlinBuildScriptModel
matching init
configure task init conditionally
configure task init
matching wrapper
configure task wrapper conditionally
configure task wrapper
matching buildEnvironment for dependsOn
matching components for dependsOn
matching dependencies for dependsOn
matching dependencyInsight for dependsOn
matching dependentComponents for dependsOn
matching foo for dependsOn
matching help for dependsOn
matching init for dependsOn
matching javaToolchains for dependsOn
matching model for dependsOn
matching outgoingVariants for dependsOn
matching prepareKotlinBuildScriptModel for dependsOn
matching projects for dependsOn
matching properties for dependsOn
matching resolvableConfigurations for dependsOn
matching tasks for dependsOn
matching wrapper for dependsOn
matching buildEnvironment for dependsOn
matching components for dependsOn
matching dependencies for dependsOn
matching dependencyInsight for dependsOn
matching dependentComponents for dependsOn
matching foo for dependsOn
matching help for dependsOn
matching init for dependsOn
matching javaToolchains for dependsOn
matching model for dependsOn
matching outgoingVariants for dependsOn
matching prepareKotlinBuildScriptModel for dependsOn
matching projects for dependsOn
matching properties for dependsOn
matching resolvableConfigurations for dependsOn
matching tasks for dependsOn
matching wrapper for dependsOn
> Task :foo UP-TO-DATE

So, whether TaskCollection.matching is fine or not, depends on the concrete usage.
If you pair it with configureEach to only configure matching tasks, it behaves perfectly fine regarding configuration avoidance.
But if you enumerate the task collection, for example by using it in dependsOn, each and every task gets realized to check the predicate, even if it results in an empty task collection like in the given example.

Page with the problem

https://docs.gradle.org/current/userguide/task_configuration_avoidance.html

[ov7a]

Thank you for your interest in Gradle!

This is a valid documentation issue that we will address.