Document behavior around -- to differentiate between task options and Gradle command-line flags

[big-guy]

When we add a new command-line option to Gradle, we run the risk that a task may have a task option with the same name. When that happens, the Gradle option wins. There's a way around this.

It's a common pattern in other tools (git, grep, etc) to use -- as a way to separate "options" from positional arguments. Gradle follows this same pattern, but there's no documentation for it. We should also check if there's test coverage.

This should be documented in our user manual but we should also consider putting something in gradle -h.

See #21154

Example

If you have this build:

abstract class MyTask extends DefaultTask {
    @Option(option="profile", description="foobar")
    void setProfile(String value) {
        System.out.println("Called setProfile")
    }
}

task mytask(type: MyTask)

If you run gradle mytask --profile, Gradle swallows the --profile as an option.

If you run gradle -- mytask --profile=foo, we treat --profile as a task option.