Describe in `cargo test --help` what `cargo test --example <example>` does

[KalitaAlexey]

Hi everybody.

During work on #3556 I have found out that I can't understand what cargo test --example <example> does.

There is no useful information in cargo test --help:
--example NAME Test only the specified example.

I can't understand what exactly it does.

[alexcrichton]

FWIW I think for now it just compiles the example, rather than executing unit tests in it (but I may have forgotten)

[KalitaAlexey]

@alexcrichton,
Yes it is.
But it isn't what test subcommand for.

[KalitaAlexey]

@alexcrichton,
It just compiles the example, but the description is Test only the specified example.
The description is wrong.

[alexcrichton]

Ok, want to send a PR to update the description?

[KalitaAlexey]

@alexcrichton,
I think we should change behavior. Can we?
My motivation is that test should test not just build.

[alexcrichton]

I don't think we can change the behavior unfortunately for backwards compatibliity

[KalitaAlexey]

@alexcrichton,
I don't think that anyone rely on the behavior.
Do you disagree about it?

[alexcrichton]

I don't think we can really say for sure either way, so we're forced to conservatively assume that someone's relying on it somewhere.

[KalitaAlexey]

@alexcrichton,
I got it. It is shame. Then I will open a PR to change the description.

[KalitaAlexey]

I have found:

cargo test runs additional checks as well. For example, it will compile any examples you’ve included and will also test the examples in your documentation. Please see the testing guide in the Rust documentation for more details.

in Cargo Guide