Documentation for --tests flag is very unclear

[jplatte]

Problem

cargo test --help has this to say about the --tests flag:

--tests                     Test all tests

Steps

1. cargo test --help

Possible Solution(s)

Explicitly state whether unit, integration and/or doctests are being run.

It seems to me like it's unit and integration tests but not doctests. If this is the intended behavior, I can create a PR to improve the help message.

Version

cargo 1.61.0-nightly (109bfbd 2022-03-17)
release: 1.61.0-nightly
commit-hash: 109bfbd055325ef87a6e7f63d67da7e838f8300b
commit-date: 2022-03-17
host: x86_64-unknown-linux-gnu
libgit2: 1.4.2 (sys:0.14.2 vendored)
libcurl: 7.80.0-DEV (sys:0.4.51+curl-7.80.0 vendored ssl:OpenSSL/1.1.1m)
os: Arch Linux Rolling Release [64-bit]

[epage]

Without having looked into it, my guess is that its running all test compilation targets and that white box tests (unit tests) are an implicit test target while docs are a special case and so not a compilation target (see #6669).

[weihanglo]

Actually, the manual in cargo help test is in more detail.

   Target Selection
       --tests
           Test all targets in test mode that have the `test = true` manifest flag set. By default this includes the library and binaries built as
           unittests, and integration tests. Be aware that this will also build any required dependencies, so the lib target may be built twice (once
           as a unittest, and once as a dependency for binaries, integration tests, etc.).  Targets may be enabled or disabled by setting the test flag
           in the manifest settings for the target.

I guess we just need to simplify it to fit in a single line.

[jplatte]

Whaaat, there's a separate cargo help foo command that outputs more info? I've been using Rust & Cargo for more than five years and I never came across that!

[epage]

clap supports a "short help" vs "long help" where -h is meant to show single-line descriptions for arguments and --help shows multi-line descriptions. I'm using this in cargo-add (#10472). I wonder if we should use it in more places instead of just relying on the man page (e.g. how does that work out for Windows users)

[tompscanlan]

I think this can close. Help output is detailed enough when requested in a specific way.

@jplatte, does knowing the detailed help exists remove the issue you were having? Do you expect to see something different?

[jplatte]

FWIW I don't think I've ever used cargo help, and I had entirely forgotten about this issue. I guess one thing that would be very helpful would be a hint about cargo help at the end of the cargo something --help output. If that's already a thing, I think this issue can be closed.

[weihanglo]

Yes, every command should already have a line at the end mentioning cargo help <command>, such as

$ cargo test --help
...
Run `cargo help test` for more detailed information.
Run `cargo test -- --help` for test binary options.

Thanks everyone for the discussion. I'll go ahead and close this. For general --help improvement, it is tracked in #6104.